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Introduction 


This document is part of the Document Interfaces Toolkit. This 
toolkit provides the interface to the GLOBALVIEW environment and 
XNS services from user-generated C programs. 





About this manual 


How chapters are organized 


Document conventions 
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The Document Interfaces Toolkit User Guide describes the 
procedure for interfacing to the GLOBALVIEW environment and to 
the XNS services by using the Document Interfaces Toolkit 
libraries. It presents general guidelines as well as examples to 
illustrate the process. 


Chapter 1, “Overview”, presents a general description of the 
Document Interfaces Toolkit. 


Chapter 2, “Desktop functions”, describes the desktop functions 
and shows how to manipulate desktop files and folders. 


Chapter 3, “XString functions”, describes the XString format and 
shows how to convert and compare XString characters and 
strings. 


Chapter 4, “Document interfaces”, presents a general workflow 
for the document-specific functions, showing procedures for 
creating and enumerating documents, graphics, and tables. 


Chapter 5, “Document function examples”, presents examples of 
using the document-specific functions. 


Chapter 6, “XNS services”, describes the XNS functions and gives 
examples of user-defined procedures that must be supplied to 
these functions. 


Chapter 7, “XNS function examples”, presents examples of using 
the XNS functions for the various XNS services. 


The Document Interfaces Toolkit User Guide uses the following 
convention: 


e Italics. VP application names, manual names, library names, 
and header file names appear in italics. 


¢ Bold. Names of properties, options, C functions, notes, and 
warnings appear in bold. 


INTRODUCTION 





Related documentation 


The following materials are recommended reading: 


e 





Document Interfaces Toolkit Reference Manual. This manual 
provides a complete list of the functions available within the 
Document Interfaces Toolkit, along with their syntax and 
argument definitions. 


UNIX Interoperability User Guide. This manual describes the 
UNIX environment and the GLOBALVIEW environment. It also 
describes how to work within each environment, switch 
between the two, and transfer information back and forth. 


Character Code Standard. This manual presents the standard 
used to assign multilingual textual information to a sequence 
of numerical codes. 


Clearinghouse Protocol. This manual presents a complete 


specification of the protocol between the Clearinghouse 


service and its clients. 


Authentication Protocol. This manual defines the complete 
specification of the protocol employed for interactions 
between clients and the Authentication Service. 


Xerox Network Systems Architecture. This manual describes 
the architecture of Xerox Network Systems, providing 
information on the standards and protocols that comprise the 
architecture. 


Filing Protocol. This manual describes the protocol for 
interaction between clients and file services. 


Printing Protocol. This manual describes the protocol used 
for communicating print requests from clients to print 
services. 


Mailing Protocol. This manual defines the set of protocols 
and related data formats for interaction between clients and 
the mail system. 


XNS for UNIX System V.3 User Guide. This manual provides 
information on the lower-level courier function calls. 
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1. Overview 


This chapter describes general information on the Document 
Interfaces Toolkit. It is assumed that the user has some 
understanding of the C programming language, the GLOBALVIEW 
environment, the VP Document Editor, and the XNS protocol. If 
more information is needed in any of these areas, please refer to 
the appropriate Xerox documents listed in the Introduction of 
this manual, or contact Xerox for a list of available training 
courses. 





What is the Document Interfaces Toolkit? 
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The Document Interfaces Toolkit allows programmers to interface 
to the GLOBALVIEW environment and Xerox Network Systems 
(XNS) from the UNIX environment. The Document Interfaces 
Toolkit consists of a set of C libraries which enable you to access 
ViewPak (VP) documents and some XNS services. With these 
libraries you may write C programs to read the contents of a VP 
document, create new documents, and append objects to the 
new document. Currently supported objects include text, tables, 
graphics, fields, and format characters. After you have created a 
new document, your C program can place the document onto 
the GLOBALVIEW hierarchical file structure, or use the XNS 
interfaces to file, mail, or print it to an XNS server. 


The document-specific operations available through the 
Document Interfaces Toolkit are: 


Place a document on the GLOBALVIEW desktop 
Create a new document 
Create graphic frames, anchored Cusp button frames, 
and text frames 
e Create new tables 
Set the properties of any objects added to a new 
document 
Append rows to existing tables 
Append frames, fields & text to documents 
Enumerate properties of existing document contents 
Enumerate the contents of a document 
Enumerate frames and their contents 


The Document Interfaces Toolkit allows you to append 
information to the end of existing documents or append rows to 
existing tables. It does not allow you to insert or change objects 
anywhere else within an existing document. You may, however, 
read the contents of a document, extract the desired 
information, and then add this information into a new document. 
More details on this process are given in Chapter 4. 


OVERVIEW 


The XNS services available through the Document Interfaces 
Toolkit are: 


Authentication 
Clearinghouse 
Printing 

Filing 

Mailing 
Gateway 


e®e@8¢ @ @ @ 


Authentication: The Authentication Service helps users and 
services determine each other’s identity in order to establish a 
communication link. A service refers to a set of software 
resources that implements XNS protocols for the user. 


Clearinghouse: The Clearinghouse is conceptually similar to a 
telephone directory. The user provides the Clearinghouse with 
object names and properties. The Clearinghouse returns the 
associated address for the names and properties. These 
addresses are used in remote procedure calls during the user’s 
interaction with XNS. 


Printing: The XNS printing application provides a set of 
procedures for transporting jobs and interpress files to the print 
service. Interpress is a Xerox standard for encoding the 
description of a document to be printed. 


Filing: The Filing Service provides the user the ability to store, 
delete, and retrieve files on an XNS file service. 


Mailing: The Mail Service provides posting and retrieving of 
electronic messages at Mail Services. 


Gateway: The Gateway Service permits users to communicate 
with systems on different networks or with different 
communication architectures. 


Note that these services allow users to access their 
corresponding servers. They do not provide the ability to 
implement your own Xerox compatible servers. 


The XNS structure is layered, meaning that the various functions 
supported by XNS are divided into a series of levels. The more 
primitive tasks are located in the lower numbered layers while the 
higher layers are reserved for more sophisticated tasks. The 
services provided by the Document Interfaces Toolkit comprise 
the Application Support Environment within the application layer, 
which is called “layer 7”. Figure 1-1 shows the relationship 
between the application layer and other layers within a layered 
network architecture. Note that the model shown in Figure 1-1 is 
an International Organization for Standardization (ISO) model. 
The XNS architecture groups some of the ISO model functions 
into fewer layers, but the general concept is the same. Please 
refer to the Xerox Network Systems Architecture General 
Information Manual for more details on the XNS structure. 
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Figure 1-1. Layers in a network architecture 
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The desktop environment 


C programs developed with the Document Interfaces Toolkit 
must be run within the GLOBALVIEW environment. The GLOBALVIEW 
desktop is the main work surface shown on your workstation 
screen. It displays icons that represent documents, file drawers, 
file folders, applications, etc. Double-clicking the mouse button 
on an icon will “open” that particular document or folder and 
reveal the document contents or a sublevel hierarchy of data, 
respectively. These icons depict the documents that the 
Document Interfaces Toolkit allow you to enumerate and to 
create. Figure 1-2 shows a typical GLOBALVIEW desktop containing 
icons and windows. 
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Figure 1-2. GLOBALVIEW desktop 
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The X Environment Window (XEW) may be described as a 
doorway from the GLOBALVIEW desktop to the UNIX environment. 
Figure 1-2 shows a snapshot of XEW in use. When opened, 
standard X Window programs compiled for a UNIX workstation 
may be executed from the desktop. In fact, it is just like having a 
UNIX X Window command tool shell loaded on your desktop. 
This window is one place where you will edit, compile, and 
invoke your Toolkit-specific programs. 


Another place C programs may run is the VP Window to UNIX 
Shell application. When you work in the VP Window to UNIX 
Shell application, it is just like using the shell command 
interpreter in UNIX. The only difference is that VP Window to 
UNIX Shell provides only simple TTY access; no graphics or other 
advanced capabilities are available. This is also the main 
difference between VP Window to UNIX Shell and XEW. Please 
refer to the UNIX Interoperability User Guide for more 
information on GLOBALVIEW, XEW and VP Window to UNIX Shell. 
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System requirements 


The following software applications must be present, enabled, 
and running on your workstation in order to use the Document 
Interfaces Toolkit: 


©  GLOBALVIEW 

e VP Document Editor 

e XEW or VP Window to UNIX Shell 
¢ DoclCToolkit 


The Document Interfaces Toolkit adheres to the hardware and 
software system requirements set forth by the GLOBALVIEW 
package. Please refer to the GLOBALVIEW documents for more 
information on system requirements. 


DOCUMENT INTERFACES TOOLKIT USER GUIDE | | ‘eng 


OVERVIEW 





DOCUMENT INTERFACES TOOLKIT USER GUIDE 


aa ae rca ee geod ee ne ee ay) 
2. Desktop functions 


The functions in the desktop portion of the Document Interfaces 
Toolkit allow for the copying, listing, and removal of files or 
folders on the GLOBALVIEW desktop. More importantly, desktop 
functions are the means by which applications written using 
Document Interfaces Toolkit C functions may interact with the 
files and folders on the desktop. 


This chapter describes the manner in which files or folders may 
be placed on the desktop, removed from the desktop, or moved 
about the desktop. 





Making and deleting folders 


Making or deleting a folder is a very straightforward process. The 
functions dsktp__makefolder() and dsktp__deletefolder() are 
called to make and delete folders, respectively. They both require 
the same arguments: 


e the name of the folder 

e the full path name of the folder in which the folder is to 
be placed or removed 

e the version number of the folder 


To make a folder called “currentProjects” inside another folder 
called “bcDoc” the following code segment may be written: 


main(argc, argv) 
char *argv{]; 


{ 
char *name; 
char *dstpath; 
XString fldrName, destPath; 
unsigned short vers; 


name = "currentProjects' ; 

dstpath = “bcDoc"; 

fldrName = (XString) malloc((strien( name) +3 + 1) 
*2); 

destPath = (XString) malloc((strien(dstpath) +3 + 1) 
*2); 

XStrfromASC(fldrName, name); 
XStrfromASC(destPath, dstpath); 
dsktp_makefolder(fldrName, destPath, vers); 


_ 


Deleting a folder is very similar in format to making a folder, so 
the dsktp__deletefolder() function will not be described here. 
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Enumerating a folder 


Listing, or enumerating, the contents of a folder is a two step 
process. The first step is to call dsktp__enumerate(). This 


function requires four arguments that specify: 


e acriteria for determining which files and folders are to be 
returned and which are to be ignored 
a path at which to begin the search 
the levels of hierarchy to descend in the search for files 
a pointer to the buffer where the list is to be placed 


The second step is to access the contents of the returned list. 


For example, to obtain a list of all the contents of a desktop, you 
may use the following code: 


main(argc, argv) 

int argc; 

char *argv[]; 

{ 

XString pattern; 
dsktp__reflist filelist; 
char | ptrn[2]; 


ptrn[0] =e 
ptrn[1] = ‘\0'; 


pattern = (XString)malloc(4); 
XStrfromASC(pattern, ptrn); 


if(dsktp enumerate(pattern, NULL, 1, &filelist) ) 
errorexit(fp); 


Here the contents of the desktop are enumerated. The entire 
desktop is enumerated as indicated by the wildcard character 
for the value of ptrn[0]. The second argument in the 
dsktp__enumerate() function is the path, and when set to NULL 
specifies the desktop. 


“Ue 


If dsktp__enumerate() returns 0, the list should be present at 
the starting address location pointed to by the &filelist 
argument. To read the list, you may add the following lines of 
code: 


for (i = 0; i < filelist.len; i+ +) { 
dsktp getdocprops(filelist.refs[i], &props); 
asciiname = (char *)malloc( 
(sizeof(char)*XStrien(props.name)) + 1); 
XStrtoASC(props.name, asciiname, subst); 
fprintf(fp, “Name is %s\n", asciiname); 
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Document reference handles 


The preceding examples illustrate the usage of basic desktop 
functions. Another important aspect of desktop functions is file 
manipulation. This usually requires additional information — a 
document handle. A document reference handle is a data 
structure that points to the file, and may be obtained by a call to 
one of several functions, such as dsktp__getdocref() or 
di__finish(). Once a document reference handle is obtained, it 
may be passed as an argument to those Document Interfaces 
Toolkit functions that either initiate or terminate the document 
editing process. 


The dsktp__getdocref() function is called first when manipulating 
a file that already exists on the desktop or in a folder on the 
desktop. The syntax for dsktp__getdocref() is: 


dsktp__getdocref( name, vers, srcpath, ref) 
where: 


e name is the text string name of the document to be 
opened 

¢ vers is an integer that specifies the version number of 
name 

¢ srcpath is the text string location of name 

e ref is the return value in which will be placed the 
document identifier 


The following example illustrates a way in which a document 
reference handle may be obtained for a document. Once the 
document reference handle is retrieved, it can be passed to 
di__start(), di_opend), etc. to start or open the document. 


main(argc, argv) 
char argv{]; 


ret open ret; 
ret__ref ref; 
XString name[256]; 


XStrfromASC(name, argv{1]); 
dsktp getdocref(name, LASTVERS, NULL, &ref); 
di _open(ref, &ret); 


} 


The arguments to the dsktp__getdocref() function in this 
example are: 


¢ name, a variable for the document name, the value of 
which is specified upon invoking the application 

e LASTVERS, a constant that specifies that the latest version 
of the document is to be accessed 

e NULL, a constant that indicates the document is on the 
desktop, rather than nested within a folder 

e ref, return value in which the document handle is placed 


Once a document handle has been successfully obtained, the 
document may be manipulated in many ways. There are three 
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dsktp__*() functions available that manipulate documents. They 
are: 


dsktp__copydoc() — copy an existing desktop file to a reserved 
buffer area 


dsktp__deletedoc() remove a document from off the desktop 


dsktp__movedoc() move document data from a buffer onto 
the desktop 





Copying and moving documents 


Copying a document is a two stage process. The first stage 
entails copying an existing document to a buffer. The second 
entails moving the buffer data onto the desktop. To copy a 
desktop document called “src__dat” to “bkup__dat”, “src__dat” 
must first be copied to a buffer. To do this call 
dsktp__copydoc(): 


main(argc, argv) 


char argv{]; 

{ 
XString name[256]; 
dsktp__docref ref; 
dsktop_docref new; 
dsktp copydoc(ref, &new ); 

} 

where: 


e ref is the document handle returned by an earlier call to 
dsktp__getdocref() 

e &new defines the structure into which the buffer 
document handle is to be placed. 


At this point, the duplicate document only resides in the buffer. 
To create an icon for the duplicate document the buffer must be 
moved onto the desktop. The dsktp__movedoc() function is 
used to move the buffer. The syntax of this function is: 


dsktp__movedoc( ref, dstpath, name, vers) 
where: 


e ref is the document handle that was returned by 
dsktp__copydoc() 

e dstpath is the full path name of the folder in which the 
file is to go 

¢ name is the text string the new document is to have as 
its name 

e vers is the version number 


Continuing with the previous example, the document in the 
buffer may be copied onto the desktop in the following manner: 


main(argc, argv) 
char *argv{]; 
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} 


DESKTOP FUNCTIONS 


char *text; 

XString name; 
unsigned short vers; 
ret scret; 

ret fcret2; 

int ok 


if (di__finish(ret.doc, NULL, NULL, &ret2)) { 


} 


text = "bcDoc.new" 

name = ( XString) malloc((strien( text) + 1) *2); 
XStrfromASC( name, text); 

ok = dsktp movedoc(&ret2.ref[0], NULL, name, &vers); 
if (ok) exit(1); 


Please see the Document Interfaces Toolkit Reference Manual 
for more detailed information on the desktop functions. 


DESKTOP FUNCTIONS 
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3. XString Functions 


The Document Interfaces Toolkit offers a set of string 
manipulation functions to perform tasks that are specific to the 
GLOBALVIEW environment. These functions are referred to 
collectively as XString functions. The string manipulation 
functions included in the Document Interfaces Toolkit are used 
primarily to convert character formats for transmission between 
UNIX (ASCIl-based) and XString-based GLOBALVIEW interfaces and 
to allow C applications to control text processing from within the 
GLOBALVIEW environment. 


This chapter describes how to use XString functions. Actual 
examples are included to further illustrate the application of 
these functions within a C program. Upon completing this 
chapter, you should be able to use XString functions to convert 
strings from Xerox Character Code formats to ASCII and back 
again, to copy strings, to compare strings, and more. 





XString format 


Xerox Character Code Standard 
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XStrings are in a special format that allow the support of a large 
number of languages. The format is described in the Xerox 
Character Code Standard. For most of the XString functions, 
there are C counterparts that provide similar functionality. The 
main difference is that XString functions operate on XStrings 
rather than simple C strings containing ASCII characters. There 
are functions which allow XStrings to be converted to ASCII 
strings and visa versa. The spelling of XString function names is 
often spelled identically to the conventional C counterparts, 
except that the XString function names are prefixed with an X. 
For example, strcat() and XStrcat(). 


They are also very similar syntactically. That is, XString functions 
require the same arguments as their conventional C counterparts. 
The syntax of strcat() is: 


Strcat(s, ct) 
The syntax of XStrcat() is: 
XStrcat(xs1, xs2) 


where, ct is the string to be concatenated to the end of s and 
xs2 is the XString to be concatenated to the end of xs1. 


An XString is a set of one or more characters that is structured in 
accordance to the Xerox Character Code Standard. All XStrings 
are represented as a sequence of numeric codes. These numeric 
codes may be used in such a way as to define characters, so that 
there is no ambiguity when communicating between various 
protocols or interchanging documents. 
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XString structure 


The Xerox Character Code Standard (XCCS) is used to define the 
meaning and the appearance of characters. Each character is 
expressed as a 16-bit entity having a numeric value between 0 
and 65,535, inclusive. Each 16-bit character code can be viewed 
as consisting of two 8-bit bytes, where the high-order byte is the 
character set code and the low-order byte is the character’s code 
within the character set. 


Figure 3-1. Character structure 
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The range of numeric codes are described and defined in the 
Character Code Standard manual. 


Some simple examples, using the 000g Character Set are used in 
this chapter. 


XString functions are available that convert 8-bit encoded XStrings 
to 16-bit encoded XStrings, and visa versa, as described in the 
Character Code Standard manual. There are also functions that 
convert XStrings from ASCII to XString formats, and visa versa. 
Conversion to and from EUC (Extended Unix Code) or JIS 
(Japanese Industrial Standard) is not currently supported. 
Conversion to and from ISO 8859 is also not supported. ISO 
8859 is a superset of ASCII that provides support for western 
European languages. 


An XChar is a character that adheres to the format specified in 
the XCCS. An XString is a simple array of XChar terminated by a 
16-bit NULL code (0x0000). 


Figure 3-2. Structure of XString 
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All XString creation and editing functions, except XStrncpy(), 
terminate the resulting XString with a NULL character. 
Furthermore, XCC8 (Xerox Character Code for 8-bit characters) is 
defined in the XCCS book as a data structure comprised of 8-bit 
encodings. XCC8 is analogous to ByteSequence in Mesa XString. - 
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String Conversion 


DOCUMENT INTERFACES TOOLKIT USER GUIDE 


The C functions in the Document Interfaces Toolkit are used to 
interact with the GLOBALVIEW environment. Internally, the 
structure of text is different than that of regular ASCII text. When 
text is passed between ASClIl-based and XString-based 
environments, it must be converted to the appropriate structure 
before the receiving environment is capable of processing it. 


There are three text structures of interest: ASCII, XString, and 
XCC8. In ASCII, a character is described in one 8-bit byte. An 
XString character is described in two 8-bit bytes. An XCC8 
character is the same as an XString character, except that it has 
been truncated into one 8-bit byte. 


To pass an ASCII string into the GLOBALVIEW environment, it must 
be converted from ASCII to an XString format. The reverse is true 
when going from XString to ASCII. There are seven XString 
functions that either generate XChars or convert strings between 
ASCII and XCCS formats. The following table is a brief synopsis 
of those XString functions. 


Table 3-1. XString usage 


XCharset Determine the character set to which an 
XChar belongs 


XCharcode Determine the code of an XChar 


XCharmake Make an XChar of a specific character set 
and code 


XStrfromASC Convert an ASCII string into an XString 
XStrtoASC Convert an XString into an ASCII string 


XStrfromXCC8 Convert an XCC8 XString into a 16-bit 
XString 

XStrtoxCC8 Convert a 16-bit XString into an XCC8 
XString 


The first three functions, XCharset(), XCharcode(), and 
XCharmake() are used to read and generate XChars. These 
functions are described in the section immediately following this 
one. 








The two most important conversion functions are XStrfromASC() 
and XStrtoASC(). XStrfromASC() is used to convert an ASCII 
string to an XString format. XStrtoASC() is called to convert text 
from an XString to an ASCII format. 


The syntax of XStrfromASC() is: 
XStrfromASC(xs, s) 


where s is a pointer to the ASCII string to be converted and xs is 
the return value which contains the XString equivalent of s. For 
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example, to convert an ASCII text string into an XString text 
string, the following code segment may be written: 


main(argc, argv) 
Int argc; 
char *argv[]; 


XString name; 
char *ascil; 


ascii = argv[1]; 
name = (XString) malloc((strlen( ascii) + 1) * 2); 
XStrfromASC(name, ascii); 


The result of the preceding code segment is an XString variable, 
called name, that may be passed as an argument to other 
Document Interfaces Toolkit functions, such as 
dsktp__movedoc(). 


The format of XStrtoASC() is: 
: XStrtoASC(xs, s) 


where xs is the XString to be converted and s is the return value 
which contains the equivalent ASCII text. 


An example of converting from XString back to ASCII is shown 
below: 


XString text work; 

XString text; 

ascii text = (char *) malloc (XStrien(text) + 1); 

text work = (XString) malloc (XStrien(text))*2 + 2); 
XStrtoASC(text__work, ascii__ text); 


XCC8 conversion 


Two functions, XStrfromXCCa() and XStrtoXCC8s() are used to 
convert strings between XString and XCC8 formats. The primary 
advantage of converting strings to an XCC8 format is that it 
compresses the strings into compact, 8-bit encoded strings. 


XStrfromXCC8() is called to convert an XCC8 string to an XString 
format. The syntax of XStrfromXCC8&() is: 


XStrfromXCC8(xs, xcc8, len, prefix) 


where xs is the storage area in which the converted XCC8 string 

will be placed, xcc8 is the 8-bit encode string to be converted, 

len is the length in bytes of xcc8, and prefix specifies the 

character set of xcc8. prefix should be -1 if the first character of 
_xcc8 begins with a 16-bit code. 


XStrtoXCC8() is called to convert an XString string to XCC8 
format. The syntax of XStrtoxCCsg() is: 


XStrtoxXCC8(xs, xcc8) 


where xs is the XString to be converted and xcc8 is the return 
value which contains the XCC8 equivalent of xs. 


The following example shows a simple usage of XStrtoxCCs(): 
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#define BUFLEN 256 
XChar xs [BUFLEN]; 
unsigned char  xcc8[BUFLEN*2]; 


len = XStrtoXCC8(xs, xcc8); 


In the above example, the value of xs is translated into XCC8 
format and is placed into the argument xcc8. len, the return 
value, returns the byte length of xcc8. 


Note that converting strings directly between ASCII and XCC8 
formats is not allowed. A string must be in an XString format 
before it may be converted to either ASCII or XCC8. 





Character identification 


When reading an XString, one of the first steps may be to 
determine the character set and the character code of the XChars 
in that XString. To determine the Character Set and the Character 
Code, calls are to be made to XCharset() and XCharcode() for 
each XChar in the XString. XCharset() is used to determine the 
Character Set (the most significant 8-bits). XCharcode() is used 
to determine the Character Code (the least significant 8-bits). 
The syntax of XCharset() is: 


XCharset(xc); 
The syntax of XCharcode() is: 
XCharcode(xc); 


The argument xc is of the type XChar, the value of which is the 
XChar for which the set or code is to be determined. 


The following example illustrates one way of determining the 
Character Set and Character Code of a character: 


#include <stdio.h> 
#include <doctk/DociCProps.h> 


main() 
{ 
ret getpagedel ret; 
char cs,cc; 
if(dp getpagedel(&ret)) { 
error display("dp getpagedel",0); 
return(-1); _ 
}: : 
cs = XCharset(ret.del); 
cc = XCharcode(ret.de); 
printf("Left (Set, Code) = (%x,%x) ", cs, CC); 





XString functions 


There are 18 XString functions that manipulate XStrings in a way 
similar to the way conventional C manipulates regular strings. 
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Table 3-2 is a brief synopsis of the XString functions that 
manipulate XStrings in a conventional C fashion. Note that the 
conventional C function listed is not necessarily identical to the 
corresponding XString function, but may be a close 
approximation. 


Table 3-2. C and XString function similarities 


XStrcat Concatenate two XStrings 


XStrncat Concatenate a specific number of 
characters from one XString to the 
end of another 


strcat 






strncat 







strcmp Xstrcmp Compare two XStrings for any 
variation, not taking into account 


the character case 







strncmp XStrncmp Compare a specific number of 
characters in one XString against 
the same number of characters in 


another XString 


XStrcasecmp Compare two XStrings, while taking 
into account the character case 


XStrncasecmp Compare a specific number of 
characters in one XString against 

the same number of characters in 
another XString, while taking into 
account the character case 


XStrcpy Copy an XString into a buffer 


XStrncpy Copy a specific number of 
characters in an XString into a 
buffer 


XStrdup Copy an XString into a buffer and 
return a pointer to the buffer 

XStrlen Determine the logical length of an 
XString 


XStrlexcmp Lexicographically compare two 
XStrings using a sort order 

parameter to support multinational 
comparisons 












strcpy 






strncpy 






strlen 





strcmp 






Lexicographically compare a 
specific number of characters in 
one XString against the same 


strncmp XStrnlexcmp 


number of characters in another 


XString not accounting for 
character case 
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Table 3-2. C and XString function similarities 


XString Use 


XStrcaselexcmp | Lexicographically compare two 
XStrings, while taking into account 


the character case 


strchr XStrchr Return a pointer to the first 
occurrence of a specified XChar in 
an XString 

strrchr XStrrchr Return a pointer to the last 
occurrence of a specified XChar in 
an XString 


strpbrk XStrpbrk Find the first occurrence of an 
XChar in an XString that also occurs 
in another XString and returns a 
pointer to it 

strstr XStrsch Determine if an XString is wholly 
contained within another XString 

strtok XStrsep Section an XString into tokens 
based upon a specified delimiter 


Concatenating XStrings 
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XChars may be concatenated with other XChars to make an 
XString. The XStrcat() function is used to concatenate XStrings, 
much like the strcat() function in conventional C. XStrcat() takes 
two arguments: The first is the XChar or XString to which another 
XChar or XString is to be added. The second argument is the 
XChar or XString to be added. The syntax for XStrcat() is: 


XStrcat(xs1, xs2); 


where xs2 is the XString to be appended to the end of XString 
xs1. 


The following example appends the characters “.CV” to an 
XString: 


XString name; 

ascii1 = argv[1]; 

- 

The following line uses (strlen(ascii1) + 4) instead of 
(strien(ascii1) + 1) in order to allocate memory for the 
additional 3 character extension 

a 

name = (XString)malloc((strien(ascii1) + 4) * 2); 
name = XStrfromASC(name, ascil) 

ascii = ".CV": 

ext = (XString)malloc((strlen(ascii) + 1) * 2); 

ext = XStrfromASC(ext, ascii); 

name = XStrcat(name, ext); 
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XString comparison 


The XStrncat() function is used to concatenate a specific number 
of XStrings in one XString to the end of another XString, like the 
conventional C function strncat(). The syntax for XStrncat() is: 


XStrncat(xs1, xs2, n); 


where n is the number of XStrings from xs2 to be appended to 
the end of xs1. 


Many occasions occur where an XString returned by a function 
must be evaluated by comparing it against another XString. 


Some Document Interfaces Toolkit functions may be used to 
compare XChars or XStrings based upon a specified criteria. The 
criteria may notice or ignore character case, compare whole 
XStrings or partial XStrings, and/or compare XStrings 
lexicographically. A lexicographic comparison compares XStrings 
based upon the nationality of the language used to define the 
XChars in the respective XStrings. 


Basic XString comparison 


To initiate an exact comparison of two XStrings, the XStrcmp() 
function should be called. The syntax of XStrcmp() is: 


XStrcmp(xs1, xs2); 
where the XChars in xs1 are compared the XChars in xs2. 


To compare one XString, “abcdef”, against another, “abcxyz”, the 
following function call may be made: 


char ascii1; 

char ascii2; 

XString xstr1; 

XString xstr2; 

int results; 

asciil = ‘abcdef’; 

ascii2 = ‘abcxyz’; 

xstr1 = (XString)malloc((strlen( ascii1) + 1) * 2); 
xstr2 = (XString)malloc((strlen(ascii2) + 1) * 2); 
results = XStrcmp(xstr1, xstr2); 


Once converted to an XString format, the XChars comprising the 
first XString, “abcdef”, are compared on a one-by-one basis 
against the XChars in the second XString, “abcxyz”. The fourth 
XChar in the second XString, “x”, is noted as being different than 
the corresponding XChar in the first XString, “d”. The value of 
XChar “d” is 0x0064(100) and that of ”x” is 0x78(120). XStrcmp() 
then returns “d - x”, which is -20 in decimal. 


Referring to the Latin Alphabet Character Set 000g shown in the 
XCCS book, you will notice the octal and hexadecimal 
equivalents of each XChar. However, XChar comparisons are 
performed in decimal. The value returned by a call to XStrcmp() 
is the difference of subtracting the decimal value of an XChar in 
the second string from that of an XChar in the first XString. In the 
preceding example, subtracting “x”, 12049, from “d”, 10019, 
results in -2049. : 


Note that whenever the return value is a positive integer, the first 
XString is numerically greater than the second XString. When the 
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return value is negative, the second XString is numerically greater. 
When the return value is 0, the two XStrings are identical. 


Partial XStrings may be compared. That is, a specific number of 
XChars in the first XString may be compared against an equivalent 
number of XChars in the second XString. The function 
XStrncmp() is used to compare a specified number of XChars in 
one XString against those of another XString. 


Comparison is performed in the same manner as described for 
XStrcmp(), except that the process initiated by this function call 
stops when the specified number of XChars have been 
compared. For example, to compare the first 5 XChars of one 
XString, “abcdef”, against the first 5 of another XString, “abcxyz”, 
the following segment of code may be used: 


char ascii1; 

char ascii2; 

XString xstr1; 

XString xstr2; 

Int results; 

Intnum; 

ascii1 = ‘abcdef’; 

ascii2 = ‘abcxyz’; 

num = 5 

xstr1 = (XString)malloc((strien( ascii1) + 1) * 2); 
xstr2 = (XString)malloc((strien(ascii2) + 1) * 2); 
results = XStrncmp(xstr1, xstr2, num); 


The decimal sum of the first five XChars of the second XString, 
53540, is subtracted from that of the first five XChars in the first 
XString, 49549. A difference of -4019 is returned. Thus, indicating 
that the sum total of the first five XChars in the second XString is 
greater than that of the first. 


Ignoring case during comparison 


The preceding functions are case-sensitive when comparing 
XStrings. Two additional functions are available in the Document 
Interfaces Toolkit that perform the same task as XStrcmp() and 
XStrncmp() but do so while ignoring the case of XChars. These 
functions are XStrcasecmp() and XStnrcasecmp(). The usage of 
these two functions is identical to that of XStrcemp() and 
XStrncmp(). 


Like XStrcmp() and XStrncmp(), XStrcasecmp() and 
XStrcasecmp() compare the decimal equivalents of XChars and 
return the difference. When converting XChars to their decimal 
equivalents; however, lowercase XChars are assigned the decimal 
value of their uppercase equivalents. Thus, the value of the XChar 
“x” is no longer 12019, but is 8849, the value of the uppercase 
“X”. So, when the return value of comparing two XStrings is 0, 
the two XStrings may not be identical but will be semantically the 
same. 


Lexicographic comparison 


Variations of the preceding functions are available which allow 
comparisons that take into account particular national sort orders 
used in some countries. They operate in the same manner as the 
other XString compare functions already described, except that 
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the lexicographic compare functions take an additional argument, 
sortorder. The other functions use a simple numeric comparison. 


The lexicographic compare functions are XStrlexcmp(), 
XStrnlexcmp(), and XStrcaselexcmp(). The syntax for these 
compare functions is: 


XStrlexcmp(xs1, xs2, sortorder); 
XStrnlexcmp(xs1, xs2, sortorder); 
XStrncaselexcmp(xs1, xs2, sortorder, n); 


where the XChars in xs1 are compared against the XChars in xs2, 
based upon the value of sortorder. n is the number of XChars in 
xs1 to be compared against the same number of XChars in xs2. 
sortorder is an enumerated type that specifies the nationality of 
interest. Valid nationalities are Standard, Danish, Swedish, and 
Spanish. Standard is the most commonly used of the sort orders. 
sortorder is explained in more detail in the Document Interfaces 
Toolkit Reference Manual. 
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4. Document interfaces 


This chapter presents a general workflow for using the Document 
Interfaces Toolkit libraries. It describes how to create and read 
documents, graphics, and tables. The XNS toolkit library is 
described in Chapter 6 of this manual. 





Document interface library 
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The document-specific portion of the Document Interfaces 
Toolkit consists of the C library /ibdoctk.a and the following 
header files: 


Desktop.h 
DocIC.h 
Doc!CProps.h 
Graphics!IC.h 
Signals.h 
Table!C.h 
XString.h 


The Desktop.h header file contains functions to enumerate, copy, 
delete, or create documents or folders on the GlobalView 
desktop. Those functions or properties prefixed with “dsktp__ ” 
may be found in the Desktop.h header file. 


The DoclC.h header file contains functions to create and 
enumerate document contents (e.g., text, fields, headings, 
footings, etc.). Those functions or properties prefixed with “di__ 
may be found in the Doc/C.h header file. 


tf 


The Doc!CProps.h header file contains functions and data types 
used to set the properties within GlobalView documents. Those 
functions or properties prefixed with “dp__” may be found in the 
Doc!CProps.h header file. 


The Graphics!C.h header file contains functions to create and 
enumerate CUSP button frames, anchored graphic frames, and 
nested graphic frames. Those functions or properties prefixed 
with “gi__” may be found in the Graphics/C.h header file. 


The Signals.h header file contains the declaration of getsigno() as 
well as error text descriptions of errors encountered during 
document manipulation. getsigno() is used to return error codes. 


The Table!C.h header file contains functions to create a new 
table, enumerate the contents of a table, and add rows to a new 
or existing table. Those functions or properties prefixed with a 
“ti_” may be found in the Table/C.h header file. 


The XString.h header file contains functions to manipulate 
characters and character strings, such as string copy, string 
comparison, string search, etc. Those functions or properties 
prefixed with an “X” may be found in the XString.h header file. 
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Error handling 


Determining the cause of an error is initiated by a call to 
getsigno(), as shown in the example below. 


if(di apaframe(&to, type, &frame, contents, FALSE, FALSE, 
FALSE, FALSE, NULL, FALSE, &anc_ret)) { 
printf("Error during appending frame: Error number 
% d\n", getsigno()) 

exit (-1); 
The getsigno() function will return an integer number. It is up to 
the programmer to develop a routine that automatically appends 
the corresponding text associated with each error number. 
Otherwise, each time an error is encountered, the user must 
manually locate the text associated with each error number from 
the Signals.h header file or the reference manual. A general 
procedure for handling errors is: 


if (di_XXX(...)) {print error(getsigno()); exit(-1);} 


void print error(number) 
int number; 


switch(number){ 
case 0x1000: printf("Doc Container Full\n");break; 
case 0x1001: printf(" Doc Document Full\n"); break; 


default: break; 


} 


In addition, some of the functions return a status code that may 
be used to check for additional errors. For example, di__start() 
returns information into the structure ret__sc, which contains the 
following members: 


di docdoc; 

di heading lhead; 
di heading rhead; 
di footing Ifoot; 

di footing rfoot; 

di numbering num; 
di scstat stat; 


stat is the status code, which may have any of the following 
values: 


SC. OK Everything was fine 

SC__DSKSP_ There isn’t enough disk space to perform the 
operation 

SC_VM There isn’t enough contiguous virtual memory 
to create the document | 


You can use this status code in your program to check for other 
errors as in the example below: 


di start(PAGINATE, FALSE, FALSE, FALSE, ifoprops, iprops, 
ipgprops, NULL, &ret) 
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if(ret.stat!= SC OK) { 
fprintf (stderr, “ret sc Status = %d/n", ret.stat); 


The preceding example checks to see if the di__start() function 
returned successfully. If not, then the code will print the error 
that ret.stat returned. The reference manual gives a complete 
description of the status code values, and which functions return 
them. 





Using the DocIC.h header file 


Creating a document 
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The DoclC.h header file provides functions to create or read the 
basic document structures, such as text, text tiles, fields, headers, 
footers, or frames. Doc!C.h functions may be used to manipulate 
the contents of text frames only. Use Graphics!C.h and 
Table!C.h functions to manipulate graphics frames or table 
frames, respectively. 


To create a new document, the first step is to call either 
di__start() or di__startap(). This sets up the data structures for 
the new document and returns a pointer to an opaque type that 
represents the document, called doc. 


The next step is to append information to the document by 
using various di__ap*() functions. Please refer to the chart in 
Table 4-1 for a listing of available di_ap*() functions. To append 
graphics or tables to the document, you must call the 
appropriate functions listed in Graphics/C.h or Table!C.h before 
using the di__apaframe() function. If you want to use 
di__starttext() to append text to an anchored text frame, call 
di__apaframe() first, then call di__starttext(). di__starttext() will 
return a text handle to which you can append information. 


When you have finished appending information to your 
document, call di__finishQ to get a reference for your new file. 


A template for creating documents is shown below: 


main(Q) 

{ 
di__start() 
di_ap *() 


[gi__*() or ti__*()] 

[di__apaframe()] 

[di__starttext()] 
di_finish() 


dsktp__movedoc() 
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Example of creating a document 


The example below creates a document, and places it on the 
lower right hand corner of the desktop. The document’s 
contents contain the line “This Document’s Name is 
<document>” where <document> is a filename given as a 
variable in the invocation of this program. 


#include <stdio.h> 

#include <malloc.h> 

#include <string.h> 

#include §<doctk/DociCProps.h> 

#include §<doctk/DociC.h> 

/* 

The following define statements set the text characteristics 
to be 18 points, and Classic font. The Doc/CProps.h header 
file will show how the font families are numbered. 

at 

#define FONT 0 

#define POINT 18 


main(argc, argv) 
int argc; 
char *argv{]; 


ret scret; 
XString name, star text; 
charinsert text[256]; 
ret fcret2; 
unsigned short vers; 
di tconttcontainer; 
inti, ok, cr; 
dp fontprops foprops; 
dp paraprops prprops; 
dp paraprops prprops2; 
dp __pageprops pgprops; 
dp breakprops bkprops; 
dp modeprops mdprops; 
dp modesel modeselect; 
‘aa 
The following lines allocate memory and retrieve the 
document's name from the dsktp movedoc function. name 
will now contain the document's name. 
sy 
name = (XString)malloc((strien(argv[1]) + 1) * 2); 
XStrfromASC(name, argv[1]); 
y= 
The following lines retrieve the default font properties, page 
properties, page break properties and mode properties. 
*/ 


dp getfontdef(&foprops); 

dp getparadef(&prprops); 

dp getparadef(&prprops2); 

dp getpagedef(&pgprops); 

dp getbreakdef(&bkprops); 

dp getmodedef(&mdprops); 

| id 
The following lines set the font to be 18 point Classic 
underlined with 1 line. FONT and POINT were set by the 
define statements above. 
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at 
foprops.fontdesc.family = FONT; 
foprops.fontdesc.size = POINT; 
foprops.udlines = 1; 
j* 
The following lines set the prprops paragraph aligned to the 
left, line height of 15, and pre-leading set to 0 


at 
prprops.basprops.Inh = 15; 
prprops.basprops.prelead = 0; 
prprops.basprops.paralign = PA LEFT; 
[ _ 


The following lines set the prprops2 paragraph to be 
centered, line height of 24, pre- and post-leading to be 6 
ss 
prprops2.basprops.iInh = 24; 
prprops2.basprops.prelead = 6; 
prprops2.basprops.poslead = 6; 
prprops2.basprops.paralign = PA CENTER; 
Ve _ 
The following line creates a new document with no header, 
no footer and no page numbers. The document will have 
font, paragraph, and page properties defined by foprops, 
prprops, and pgprops above. The first new paragraph 
character and page format characters will have default 
values. The finished document is to have simple pagination. 
*/ 
if(di start(1, FALSE, FALSE, FALSE, &foprops, &prprops, 
~ &pgprops, NULL, &ret )) exit (-1) 
/* 
The following lines create the text string "This Document's 
Name is <value of argv[1]> and place it into the character 
string insert text. A carriage return is also appended to the 
text string. 
*/ 
Sstrcpy(insert text, “This Document's Name is "); 
strcat(insert text, argv[1]); 
cr = strien (insert text); 
insert text[cr] = Ox0d; 
insert text[cr+1] = ‘\0'; 
/* _ 
The following lines allocate memory for the variable 
star textand then copies the value of insert textinto 
star” text. _ 
*/ rae 
star text = (XString)malloc(strien(insert text) * 2 + 2); 
XStrfromASC (star text,insert text); 
i _ _ 
The following lines set the text container type to bea 
document, and set handle to be ret.doc. 
a 
tcontainer.type = TC DOC; 
tcontainer.h.doc = ret.doc; 
[= 
The following lines append the text string contained in 
star texttothe text container.star text memory is then 
freed. _ 
*/ 
if(di aptext(&tcontainer, star text, &foprops )) 
~ exit(-1); — 


free(sta r_text); 
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/* 
The following line sets the current paragraph to those 
properties defined by prprops2. 
* 
/ 


if(di setpara(&tcontainer, &prprops2)) exit(-1 ); 
/* 7 
The following line appends five new paragraph characters 
with page and paragraph properties specified by prprops, 
and foprops. 
* 
/ 


if(di apnewpara(&tcontainer, &prprops, &foprops, 5) ) 
~ exit(-1); 
i* 
The following line appends a page break character using 
break properties specified in bkprops, and font properties 
specified in foprops, 
ay 
if(di apbreak(&tcontainer, &bkprops, &foprops )) 
~ exit(-1); 
/* 
The following lines set the document to display the structure 
and non-printing characters. 
* 
/ 
mdprops.strct = TRUE; 
mdprops.nonprint = TRUE; 
if(di setmode(ret.doc, &mdprops, modeselect )) 
~ exit(-1); 
/* 
The following lines close the document, and release the 
document handle. 
* 
/ 
if(di_  finish(&ret.doc, NULL, NULL, &ret2 )) 
~ exit(-1); 
/* 
The following lines move the document to the desktop, and 
give the document the name specified by name. The memory 
for name is then deallocated. 
* 
/ 
if(dsktp movedoc(&ret2.ref[0], NULL, name, &vers)) 
exit (-1); 


free(name); 


When creating and naming new documents, you must adhere to 
the legal character set of the GlobalView environment. The legal 
character set of the GlobalView environment is defined in the 
Xerox Character Code Standard. 


Setting properties 


In the preceding example, some font properties are set to non- 
default values. Specifically, the type is to be 18-point Century 
and underlined with 1 line. This was accomplished through the 
statements 


#define FONTO 
#define POINT 18 


dp _fontprops foprops; 
dp _getfontdef (&foprops); 
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foprops.fontdesc.family = FONT; 
foprops.fontdesc.size = POINT; 
foprops.udlines = 1; 


if(di start(1, FALSE, FALSE, FALSE, &foprops, &prprops, 
&pgprops, NULL, &ret)) exit (-1); 


Looking in the dp__ props section of the Document Interfaces 
Toolkit Reference Manual, you'll notice that dp__fontprops is 
the main data type used to describe the font properties. 
dp__fontprops defines the font characteristics, whether the 
characters are underlined, subscript, superscript, etc. Setting the 
members associated with this property affects the visual aspects 
of the text string accordingly. In the preceding example, visual 
aspects of the text were changed based upon the values 
assigned to the members of dp__fontprops. The reference 
manual, and the Doc/CProps.h header file, list the members of 
dp__fontprops. The members are: 


dp__fontdesc fontdesc; 
unsigned udlines; 
dp__bool stkout; 
dp__place place; 
dp__bool tobedel; 
dp__bool revised; 
dp__width width; 
XString stylename; 
dp__fontelmarr ntrelm; 
dp__bool tranpare; 
dp__color txtcol; 
dp__color hlicol; 


In addition, fontdesc contains the members 
dp__family family; 
dp__dvariant dvariant; 
dp__weight weight; 
unsigned short size; 

Now, to set the font properties, the following line: 
dp __getfontdef(&foprops); 


initializes all the font properties to the following values: 


dp__fontdesc fontdesc; 


unsigned udlines; /* 0 - no underlines */ 

dp__bool stkout; /* FALSE - do not strikeout 
characters */ 

dp__place place; /* PL__NULL - standard position, i.e. 


text is not superscript nor 
subscript */ 


dp__bool tobedel; /* FALSE - text is not marked for 
deletion in redlining mode*/ 

dp__bool revised; /* FALSE - text is not typed while 
redlining enabled */ 

dp__width width; /* WD__PROP - proportional, i.e. 
normal spacing */ 

XString stylename; /* NULL - no style sheet name */ 


dp__fontelmarr ntrelm; /* TRUE - all elements of ntrelm are 
set to true, meaning neutral 
elements of the style property */ 


DOCUMENT INTERFACES 


Enumerating a document 


dp__bool tranpare; /* TRUE - text is painted transparent, 


not solid*/ 
dp__color txtcol; /* 0,0,0 text color is black */ 
dp__color hlcol; /* 10000,0,0 highlighted text color 
is white */ 


dp__getfontdescdef() is used to set its members to the 
following values: 


dp__family family; /* FMY__FRUT - frutiger, also known 
as modern */ 

dp__dvariant dvariant; /* DV__ROMAN - numbers 
displayed in roman */ 

dp__weight weight; /* WT__MEDIUM - text weight is 
medium */ 

unsigned short size; = /* 12 - 12 point text */ 


In the example, all the default values except for dp__family, size, 
and udlines are kept. Once again, by referring to the reference 
manual or to the Doc/CProps.h header file, you will see that the 
example must set dp__family to 0 to get Classic font, size to 18 
to get 18-point text, and udlines to 1 to get underlining with a 
single line. The default values of these variables are overridden 
by the following lines: 


#define FONTO 

#define POINT 18 
foprops.fontdesc.family = FONT; 
foprops.fontdesc.size = POINT; 
foprops.udlines = 1; 


Now, when di_start() is called, the text font within the 
document will be 18-point Classic font with a single underline. 


if(di start(1, FALSE, FALSE, FALSE, &foprops, &prprops, 
&pgprops, NULL, &ret)) exit (-1); 


Page properties, paragraph properties, and other properties are 
set in a similar manner. Properties and their default values may 
be found in the Document Interfaces Toolkit Reference Manual. 


Document enumeration and creation are two separate activities. 
Functions and handles associated with one activity should not be 
used with the other. Enumeration is only the listing or displaying 
of text or properties. As such, it is a read-only process. No 
editing should be attempted while enumeration is in progress. 
Likewise, no enumeration should be attempted while creating a 
document. 


The first step in enumerating a document is to call the 
dsktp__getdocref() function. This function requires the name and 
version of the document to open. dsktp__getdocref() then 
returns a file handle for that document. This file handle may then 
be passed as an argument to other functions. You may then call 
di__open() to open the document. This causes a specific handle 
to be returned. In this case, the handle returned not only 
identifies the files to be manipulated, but indicates that the 
appropriate data structures have been set. The next step is to 
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pass the doc handle and a di_enumprocs structure into the 
di__enumerate() function. The di_enumprocs structure 
contains a set of call-back procedures, one for each of the 
following types of structures: anchored frame, break character, 
field, footnote, index, new paragraph, page format character, text 
or tile. These call-back procedures are not provided in the 
Document Interfaces Toolkit, and must be written by the 
programmer. 


di__enumerate() proceeds sequentially through the document, 
starting at the beginning of the document. As di_enumerate() 
encounters different structures within the document, it calls the 
appropriate call-back procedure. If no call-back procedure has 
been written for a specific structure, that structure will be 
ignored. Each of these call-back procedures returns a Boolean 
value. If any one of these procedures returns TRUE, the 
enumeration process will terminate immediately. If the return 
value is never TRUE, the enumeration will continue to the end of 
the document. 


When the enumeration process is complete, call di__close() to 
free all associated data structures and close any open file handles 
associated with the document. 


A simple template for enumerating documents is shown below: 


main() 

{ 
dsktp__getdocref() 
di_open() 


di__enumerate() 
di__close() 


dsktp__movedoc() 
} 


Example of enumerating a document 


#include <stdio.n> 

#include <malloc.h> 

#include <string.h> 

#include <doctk/DociCProps.h> 
#include <doctk/DociC.h> 


FILE *fp; 
short ufileflag = FALSE; 


externdp bool find text(); 

externdp bool find newpara(); 

externdp bool find  field(); 

externdp bool find index(); 

/* i i 

The following lines create an error display routine used in 
this program to display errors and error numbers if 
encountered 

*/ 

interror display(str, no) 

char *str; — 
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int no; . 


if (no = = 0) no = getsigno(); 
fprintf(stderr," Error: %s\n Error No. = %X\n", str, no); 


/* 

The following routine is a call-back procedure to find the 
index 

* / 

dp boolfind index(cdat, foprops, ixprops, index) 

void (*cdat); 

dp fontprops *foprops; 

dp indexprops *ixprops; 

di index index; 


di tcontinindex; 

di enumprocs procs; 

dp bool stops; 
ia _ 
The following line sets all elements of di enumprocs to NULL 
*/ ne 

di getenumprocsdef(&procs); 
hg 2 
The following lines identify the routines find newpara and 
find text as the routines to find a new paragraph and text 


respectively 

*/ 
procs.newpara = find newpara; 
procs.text = find text; 

[* _ 


The following lines identify the object type tobe TC INDEX, 
and the handle to be index ~ 
* 
/ 

inindex.type = TC INDEX; 

inindex.h.index = index; 
/* 
The following lines enumerate the text container inindex, 
using the call-back procedures defined by procs, and will not 
include page numbering patterns, as indicated by the FALSE 
value for the mrgnum argument 


* 
/ 
if (di enumerate(&inindex, &procs, cdat, FALSE, &stops)) 
error display( “Enumerate”, 0); 
return( TRUE); 
return( FALSE ); 
} 
/* 


The following routine is used to find fields within the 
document 
of 
dp boolfind  field(cdat, foprops, fiprops, field) 
void(*cdat); 
dp fontprops *foprops; 
dp fildprops *fiprops; 
di field field; 
,— 
di tcont infield; 
di enumprocs procs; 
dp__bool stops; 
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yi 
The following line sets all elements of di enumprocs to NULL 
*/ = 
di getenumprocsdef(&procs); 
fom 


The following lines identify the routines find newpara and 
find text as the routines to find a new paragraph and text 
respectively 
*/ 

procs.newpara = find newpara; 

procs.text = find text; 
/* _ 
The following lines identify the object type tobe TC FIELD, 
and the handle to be field _ 
* 

/ 

infield.type = TC FIELD; 

infield.h.field = field; 
Yh 
The following lines enumerate the text container using the 
call-back procedures defined by procs, and will not include 
page numbering patterns, as indicated by the FALSE value for 
the mrgnum argument 


* 
/ 
if(di enumerate(&infield, &procs, cdat, FALSE, &stops)) { 
error display( “Enumerate", 0); 
return( TRUE); 
return(FALSE ); 
/* 


The following routine adds a newline character to the 
output file 
* 


dp bool find newpara(cdat, foprops, prprops ) 
void *cdat; 

dp fontprops *foprops; 

dp paraprops *prprops; 

= 


/[* 
The following lines place a newline character in the output 
file if it exists. ufileflag is set to TRUE in the main program if 
an output file is specified in the invocation of the program 
*/ 
if (ufileflag = = TRUE) { 
if (fputs ("\n", fp) < 0) £ 
fprintf(stderr, “output file write error.\n"); 
return(TRUE); 


else { 
fprintf(stdout, “\n"); 
return (FALSE); 
dp boolfind text(cdat, foprops, text ) 
void (*cdat); 
dp fontprops *foprops; 
XString text; 


shorti = 0,j = 0; 
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char “ascii text; 
XString text work; 
j* a 
The following lines allocate memory for the text string 
variables 
*/ 
ascii text = (char *)malloc(XStrien(text) + 1); 
text work = (XString)malloc (XStrilen(text) * 2 + 2); 
[* = 
The following lines add the document character strings to 
the text work variable 
*/ er 
while (i < XStrien(text) ) { 
if (*(text +i) < 0x0080 ) { 
*(text work +j) = *(text +i); 
jt +3 


it +; 


/* 

The following line adds the null character to the end of the 
text string as per the C requirements 

*/ 


*(text work+j) = ‘\0; 
be -_ 
The following lines convert the XString text to ASCII format 
so that it may be appended to the output file 


* 
/ 
if (XStrtoASC(text work, ascii text)) { 
fprintf(stderr, "Bad string occurred !\n"); 
return(TRUE); 
/* 


The following lines add the text string to the output file if it 
exists. ufileflag is set to TRUE in the main program if an 
output file is specified in the invocation of the program 
*/ 
if (ufileflag = = TRUE) { 
if (fputs(ascii text, fp) < 0) { 
fprintf(stderr, “output file write error.\n"); 
return (TRUE); 


else { 
fprintf(stdout, “%s",ascii__ text); 


/* 
The following lines use the UNIX memory deallocation call to 
free the memory assigned to the text string variables 
*/ 
free(ascii text); 
free(text work); 
return(FALSE ); 


} 

/* 

The following routine is the main program 
*/ 

main(argc, argv) 

int argc; 

char *argv{]; 
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dsktp docref ref; 
di docsdoc; 
di enumprocs procs; 
ret open ret; 
XString name[256], star text[256]; 
charinsert text[256]; 
unsigned short vers; 
di tcont tcontainer; 
dp bool mrgnum, stops; 
inti, ok; 
/* 
The following lines check for invocation syntax errors, and if 
the output file can be opened successfully 
*/ 
if (argc < 2) { 
fprintf(stderr, “usage: %sdocument name 
[UNIX filename] \n", argv[O]); ~~ 
exit(1); 


} 
if (argc > 2) { 
ufileflag = TRUE; 
if ((fp = fopen (argv[2], "w")) = = NULL) { 
fprintf(stderr, "Destination file Open Error 
Mn"); 
exit(1); 


} 


XStrfromASC (name, argv[1]); 
/* 
The following lines retrieve the latest version of the 
document from the desktop 


* 
/ 
ok = dsktp getdocref (name, LASTVERS, NULL, &ref[0]); 
if(ok){ 
fprintf (stderr, “Can't get document 
reference.\n'); 
exit (1); 
[* 
The following line opens the document 
| 
if(di open(ref, &ret)) error display( “Open”, 0); 
as -< _ 


The following lines set the text container to be document, 
and set text handle to be ret.doc and sdoc 


*/ 
tcontainer.type = TC DOC; 
tcontainer.h.doc = ret.doc; 
sdoc = ret.doc; 
mrgnum = FALSE; 

/* 


The following line sets all elements of di enumprocs to NULL 
*/ is 

di getenumprocsdef( &procs ); 

i 


The following lines set the callback procedures to the 
following routines defined earlier in this program 
*/ 

procs.newpara = find newpara; 

procs.text = find text; 
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procs.field = find field; 
procs.index = find index; 


j* 
*/ 
if(di enumerate (&tcontainer, &procs, &sdoc, mrgnum, 
~ &stops)) { 
error display( “Enumerate”, 0); 
di close( &ret.doc); 
exit( 1 ); 
pe 
The following line finalizes and closes the document 
ad 


if(di close(&ret.doc)) error display( "Close", 0); 
fclose(fp); _ 


Use the following charts may be used as an aid to the selection 
and application of di__*() functions. Detailed information 
regarding each function may also be found in the Document 
Interfaces Toolkit Reference Manual. 


Table 4-1. Usage of di__*() functions 


Object 3 


di_yeter 


Tee | 














Anchored Text 
Frame 






di__textforaframe 
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Table 4-1. Usage of di__*() functions 


Object — 

Footnote , 
di__apaframe di__fnpropsproc 

di__fntile di__getfnprops 

di__relcap di__fntileproc 


di__apaframe di__aframeproc 
di__relcap 
di__apbreak di__breakproc 
Field di__ field di__fieldproc 
di__relfield di__getfieldfromname 


Index di__apindex 
di__relindex 
| New paragraph di__apnewpara 
di__setpara 


Page (Header, di 
di__relhead | di BSeowe | 
di__relfoot | 
di__relnum | 
I 


Other Anchored 
Frames 





{__indexproc 





d 
di__newparaproc 











Footer, 


Numbering) 
di__sfbrkproc 3 


SoftPageBreak = 
| FilllnOrder di__aptofillin di__fillinproc 
di__clearfillin di__enumfillin ) 
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Object 


di__styleproc di__fstyleproc 
d 


= 
i 
di__pstyleproc 
i__ 
os 














d 
TextLink di__aptotxtInk di__txtInkproc 
di__cleartxtInk di__enumtxtink 
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The Graphics!C.h header file contains functions and properties 
used in the creation and enumeration of graphic frames. 


Graphics may be created and added to a document which is 
currently open for editing. Graphics creation is initiated by a call 
to gi__startgr(). This function creates a graphics container and 
returns a handle. 


The returned handle from gi__startgr() identifies the graphics 
frame in which graphics data is to be placed. The handle is then 
passed as an argument to various gi__ad*() functions when 
adding new graphic objects. Depending on the function called, 
you may add graphic objects like curves or rectangles, bitmap 
frames, or text frames to the graphics frame. 


Nested frames, such as non-anchored graphics frames, CUSP 
buttons, or graphics clusters may also be added to the graphics 
frame. A nested frame is simply a frame placed within a larger 
frame. gi__startgframe(), gi__startnbtn(), gi__startcluster() 
functions create the respective nested frame listed above. 


When everything has been added to the graphics container, the 
final step is a call to gi__finish*(). The following is a template of 
the graphics creation process: 


main({) 
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di__start() 
gi__startgr() 
gi__ad*(h) 
gi__finish*() 
di_apaframe() 
di__finish() 


dsktp__movedoc() 
} 


Example of generating graphics 


An example of the graphics generation process is shown below. 
In this example, a new document file is created, an anchored 
graphic frame is added to the document, and a curve is inserted 
within the graphic frame. The document is then placed on the 
lower right corner of the desktop. The following calls are made 
in this example: 


di__ start() 
gi__startgr() 

gi_ get*() 
gi_ad*() 
gi__finishgr() 
di__apaframe() 
di__finish() 


The example program is listed below: 


#include <stdio.h> 

#include <doctk/DoclCProps.h> 
#include <doctk/DociC.h> 
#include <doctk/XString.h> 
#include <doctk/Desktop.h> 
#include <doctk/GraphicsiIC._h> 


main (argc,argv) 
int argc; 
char *argv{]; 


{ 


ret scret; 
ret fcret2; 
XString name; 
di tcontto; 
di aframetype type; 
gi handleh; 
gi box box; 
gi curveprops props; 
di ins contents; 
dp frameprops frame; 
ret apaframeanc ret; 
char *ascii; — 
unsigned short vers; 

/* 
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The following line creates a document with no header, 
footer, or page numbers and uses default values for the 
page, font, and mode properties 
* 
/ 
if(di start(PO COMPRESS, FALSE, FALSE, FALSE,NULL, 
~ NULL, NOLL, NULL, &ret)) exit(-1) 
[* 
The following line creates a graphics frame, where h is the 
handle to the frame 
* 
/ 
if(gi startgr(ret.doc,&h)) exit (-1) 
/* = 
The following lines initialize graphics frame box and curve to 
their default property values 
* 
/ 
gi getboxdef(&box); 
gi getcurvepropsdef(&props); 
Ee 
The following line adds a curve with properties defined by 
&props 
*/ 
if(gi adcurve(h,&box,&props)) exit (-1) 
/* _ 
The following line frees the graphics handle 
* 


if(gi_ finishgr(h,&contents)) exit (-1) 
ba _ 
The following lines set the text container to be a document, 
and set text handle to be ret.doc 
*/ 
to.type = TC DOC; 
to.h.doc = ret.doc; 
/* 
The following line defines the type of frame to be appended 
as a graphics anchored frame 
* 
/ 
type = AF GRAPH; 
hi _ 
The following line retrieves the default properties of the 
anchored frame 
*/ 
if(dp getframedef(&frame)) exit (-1) 
he _ 
The following line appends the graphics frame to the 
document with contents from gi finishgr. No captions are 
placed; use default font properties. Frame size automatically 
adjusted to fit existing frame 
* 


if(di apaframe(&to, type, &frame, contents, FALSE, 
~ FALSE, FALSE, FALSE, NULL, FALSE, &anc_ret)) exit 
-1 -= 
- (-1) 


The following line finalizes the document, and releases the 
document handle 
i 
if(di_ finish(&ret.doc,NULL,NULL, &ret2)) exit (-1) 
/* = 
The following lines retrieve the name of the document, and 
place it onto the desktop 
*/ 


ascii = argv[1]; 
name = (XString)malloc((strlen(ascii) + 1) * 2); 
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XStrfromASC(name,ascil); 
dsktp movedoc(&ret2.ref[0], NULL,name, &vers); 


The gi__enumerate() function is used to read the contents and 


properties of a graphic frame. It reads the contents of the 


graphic frame, and calls the appropriate call-back procedure for 
each object encountered. The graphic frame and user-defined 


call-back procedures are supplied as arguments to 
gi__enumerate(). If an object is encountered for which a call 
back procedure has not been defined, that object will be 
ignored. 


Example of enumerating graphics 


#include <stdio.h> 

#include <doctk/DoclC.h> 
#include <doctk/DocliCProps.h> 
#include <doctk/GraphicsiIC.h> 
#include <doctk/XString.h> 
#include <doctk/Desktop.h> 
/* 


The following routine, curveproc, simply prints out all the 


properties associated with any encountered curves 
*/ 

dp bool curveproc(cdat, box, props) 

void *cdat; 

gi_box *box; 

gi _Ccurveprops “props; 


printf("**** curve's box & a part of curve props 
values ****\n"); 
printf("box.place.[x,y] = [%d, %d] (mica)\n", 
box->place.x, box->place.y); 
printf("box.dims.[w,h] = [%d, %d] (mica)\n", 
box->dims.w, box->dims.h); 
printf(“curveprops.brsh.wth = %d\n", 
props- >brsh.wth); 
printf(“curveprops.brsh.stylebrush = %d\n", 
props->brsh.stylebrush); 
printf("“curveprops.brsh.brushcolor.y = %d\n", 
props->brsh.brushcolor.y); 
printf("curveprops.brsh.brushcolor.e = %d\n", 
props- >brsh.brushcolor.e); 
printf(“curveprops.brsh.brushcolor.s = %d\n", 
props- >brsh.brushcolor.s); 
printf(“curveprops.Inenw = %d\n", props->Inenw); 
printf("curveprops.inese = %d\n", props->Inese); 
printf(“curveprops.iInhnw = %d\n", 
props- >Inhnw); 
printf("curveprops.Inhse = %d\n", props- >Inhse); 
printf("curveprops.pinw.x = %d\n", 
props- >plnw.x); 
printf("curveprops.pinw.y = %d\n", 
props- >plinw.y); 
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printf("“curveprops.plapx.x = %d\n", 
props- > plapx.x); 
printf("curveprops.plapx.y = %d\n", 
props->plapx.y); 
printf("curveprops.plse.x = %d\n", props->plse.x); 
printf("curveprops.plse.y = %d\n", props->plse.y); 
printf("curveprops.plpek.x = %d\n", 
props- > plpek.x); 
printf("curveprops.plpek.y = %d\n", 
props- >plpek.y); 
printf("curveprops.eccentric = %d\n", 
props- > eccentric); 
printf("curveprops.eccentricity = %d\n", 
props- > eccentricity); 
printf(“curveprops.fixangle = %d\n", 
props- > fixangle); 


} 
/* 
The following routine, aframeproc, is the call-back 
procedure that is called when an anchored graphics frame is 
encountered within a document 
| 
dp bool aframeproc(cdat, type, font, frame, props, cont, 
~ tcap, beap, Icap, reap) 
void *cdat; | 
di aframetype type; 
dp fontprops *font; 
di ins frame; 
dp frameprops *props; 
di ins cont; 
di caption tcap; 
di caption bcap; 
di caption Icap; 
di__caption rcap; 
{ 
dp _ bool stops; 
gi__enumprocs gprocs; 
/* 
The following line checks to see if an an anchored graphics 
frame has been encountered, and has some contents 


* 

/ 

if(type = = AF GRAPH &&cont! = NULL) { 
/* a 
The following line sets all elements of gi_enumprocs to NULL 
=) 
gi getenumprocsdef(&gprocs); 

[* 7 


The following line identifies curveproc as the call-back 
procedure if a curve is encountered 
ay 
gprocs.curve = curveproc; 
yk 
The following line is the enumeration process, using the call- 
back procedures as defined by gprocs 
*/ 
if(gi_ enumerate(frame, gprocs, NULL, &stops) 
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'= 0){ 

printf(" Error(gi enumerate) getsigno = 
%x\n", getsigno() ); 

return(TRUE); 


} 


} 
return(FALSE); 
} 


/* 

The following routine is the main program for enumerating 
graphics 

| 

main( argc, argv) 

int argc; 

char *argv{]; 


{ 
ret openret op; 
dsktp docref ref; 
di tcontto; 
XString name; 
di enumprocs procs; 
dp bool stops; 
/* 7 
The following lines allocate memory for the document, 
translate the ASCII name into an equivalent XString format, 
and then retrieve the document from the desktop 
a 
name = (XString)malloc((strlen(argv[1]) + 1) * 2); 
XStrfromASC(name, argv[1]); 
if(dsktp getdocref(name, LASTVERS, NULL, 
&ref[0])) { 
printf(" Error(dsktp getdocdef) 
getsigno = %x\n", getsigno()); 
exit(-1); 
} 
/* 


The following lines open the document, and returns an error 
message if the open is unsuccessful 


*/ 
if(di open(ref, &ret op)) { 
~ printf(" Error(di open) getsigno = %x\n", 
getsigno()); 
exit(-1); 
} 
if(ret op.status!= OP OK) { 
“printf("error status = %d\n",ret op.status); 
exit(-1); _ 
} 
/* 


The following lines set the text container to be a document, 
and the text handle to beret op.doc 
*/ ats 
to.type = TC DOC; 
to.h.doc = ret op.doc; 
/* 7 
The following line sets all elements of di__enumprocs to NULL 
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* 
/ 
di getenumprocsdef(&procs); 
fe * 
The following line identifies aframeproc as the call-back 
procedure if an anchored frame is encountered 
* 
/ 
procs.aframe = aframeproc; 
[* 
The following line enumerates the document, using the call- 
back procedures defined by &procs 


*/ 
if(di enumerate(&to, &procs, NULL, TRUE, &stops)) £ 
~ di close(&ret op.doc); 
exit( 1); _ 
} 
/[* 


The following lines close the document, and returns an error 
message if the close function is unsuccessful 


ig 
if(di close(&ret op.doc)) { 
~ printf(" Error(di close) getsigno = %x\n", 
getsigno()); 
exit(-1); 
} 
} 


The following charts may be used as an aid to the selection and 
application of gi__*() functions. Detailed information regarding 


-each function may also be found in the Document Interfaces 


Toolkit Reference Manual. 
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Table 4-2. Anchored graphic and anchored button frame 
functions 


Anchored 









gi__getgframeprops 


gi__startgr 





Graphics 





gi__finishgr 





Frame 





gi__setgframeprops 


gi__startbtn gi__btnforaframe 
gi__finishbtn gi__enumbtnprog 


gi__relbtnprog 
gi__apchartobtnprog 
gi__apnparatobtnprog 
gi_aptexttobtnprog = | 


Table 4-3. Graphic objects and related functions 







Anchored Button 
Frame 

















Reading 
Parga Ory Objects 


Function Name — Function Name 


Point gi__adpoint gi__pointproc 


i__rectangleproc 


gi 
Objects 
Ellipse i__adellipse gi__ellipseproc 
i g 
g 
i 


Blas 
Rectangle gi__adrectangle 
gl__ 
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Table 4-3. Graphic objects and related functions 


Frame oe 





5 


Nested 


Graphics Frame 





i 
I 
gi__startgframe i__frameproc 
gi__finishgframe —— | 

Nested Button gi__startnbtn 


Frame 
gi__enumbtnprog 





gi__finishnbtn 
gi__relbtnprog 
gi__apchartobtnprog 


gi__apnparatobtnprog 





gi__aptexttobtnprog 


gi__adbacht gi__bachtproc 
gi__adIncht gi__Inchtproc 
gi__adpicht gi__pichtproc 


Chart 
8 


gi__clusterproc 


i__startcluster 


Others Cluster 
gi__finishcluster 








Using the Table!IC.h header file 


A table is defined by three types of properties: table, column, 
and row. Table properties specify the name of the table, a 
description of the table headers, and the number of columns and 
rows in the table. Column properties determine how the 
columns are to be divided, and how text is to be aligned within 
the columns. Row properties determine how the text is to be 
aligned within each row. The actual contents of a table are 
included as a member of the row properties. 
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A new table is initiated upon calling ti__starttable(). Table 
properties and column properties are passed to ti__starttable(), 
which returns a table handle, Handle. The table handle is a 
pointer to Object. Object is an enumerated type that contains 
table-related data and a pointer to the actual table contents. 
Initially, the row properties have default values so the table will 
have no contents. After calling ti__starttable(), you may add 
contents and properties to each row via calls to other ti*__() 
functions. 


To add contents to the table, pass the table handle to 
ti_appendrow(). When all the rows have been added, finalize 
the table by calling ti_finishtable(). 


ti__finishtable() returns an instance of the table called di__ins, 
which you can then pass to di_apaframe() or gi__adtable(). 

The remaining table frame properties, like captions and border 
style, are handled by calls to DociC and GraphicsI/C functions. 


To add information to an existing table, you should call 
ti__startextable() instead of ti__starttable(). ti__startextable() 
also returns a table handle, which may then be passed to 
ti__appendrow() and later to ti__finishtable(). ti__startextable() 
requires a di__ins as an argument which may be obtained from 
di__enumerate(). The handle of the document to be 
enumerated must come from di_startap(). 


Example of generating a table 


#include <stdio.h> 

#include <string.h> 

#inciude <malloc.h> 

#include <doctk/DociCProps.h> 
#include <doctk/DociC.h> 


#define PAGINATE PO COMPRESS 


extern int createTable(); 
[* | 
The following lines create an error display routine used in 
this program to display errors and error numbers if 
encountered 
*] 
interror display(str, no) 
char *str; 
int no; 
{ 

if(no = = 0) no = getsigno(); 

fprintf(stderr," %s Error error No. = %X 

\n", str, no); 

exit(1); 

}: 


main(argc, argv) 
int argc; 
char *argv({]; 


{ 
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XString iDocName; 
ret scret; 
ret fcret2; 

ret apaframe ret3; 

unsigned short vers; 

inti, numChar, ok; 
/* 
The following lines set the font, paragraph, and page 
properties to their default values 


ei | 
dp fontprops foprops, *ifoprops = NULL; 
dp paraprops prprops, *iprprops = NULL; 
dp pageprops pgprops,*ipgprops = NULL; 
dp _breakprops bkprops; 
dp modeprops mdprops; 
dp modesel mdselect; 

/* 


The following lines check for length of document name, 
memory allocation problems, and invocation syntax errors 
a 
switch (argc) { 
case 1: 
iDocName = NULL; 
break; 
case 2: | 
numChar = strien(argv[1] ); 
if (numChar > 100) { 
fprintf(stderr, " too long 
document name \n" ); 
exit(1); 
}; 
iDocName = (XString)malloc( 
sizeof (XChar) * (numChar + 1)); 
if (iDocName) XStrfromASC 
(iDocName, argv[1] ); 
else error display ("Malloc", 1); 
break; 
default: 
fprintf(stderr, "usage: %s 
document name \n", argv(0] ); 
exit( 1); _ 


/* 

The following line creates a document with no header, 
footer, or page numbers. The font, paragraph and page 
properties are defined by ifoprops, iprprops, and ipgprops 
above. The first new paragraph character and page format 
character will have default values 


* 
/ 
«it ( di__start( PAGINATE, FALSE, FALSE, 
FALSE, ifoprops, iprprops, ipgprops, NULL, &ret )) 
error display( "Start", 0); 
/* — 
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The following lines check to see if the document was created 
or opened successfully. If not, then, give error status 
number and abort 
al 
if(ret.stat!=SC OK) € 
fprintf(stderr, "ret scstatus = %d\n", 
ret.stat ); = 
if(di abort (&ret.doc )) exit(-1); 
exit(1); 
J 


for(i = 0;i<= (int)ME PROMPT;i+ + ) 
mdselect[i] = TRUE; 

/* 
The following lines set the document to show structure, 
show non-printing characters, not to display cover sheet, and 
not to prompt for field 
at | 

mdprops.strct = TRUE; 

mdprops.nonprint = TRUE; 

mdprops.cover = FALSE; 

mdprops.prompt = FALSE; 


if(di_setmode (ret.doc, &mdprops, 
mdselect)) exit (-1 ); 
is 
The following line calls the createTable routine to create the 
table for this document 


* 
/ 
if (createTable (&ret.doc, &ret3)) 
error display ("“CreateTable", 0); 
is a 
The following line finalizes the document 
* 
/ 
if (di__finish(&ret.doc, NULL, NULL, &ret2)) 
error display ( "Finish", 0); 
/* a 


The following line moves the document to the lower-right- 
hand corner of the desktop 


*/ 
ok = dsktp movedoc(ret2.ref, NULL, 
iDocName, &vers ); 
fprintf(stderr,” End ofdsktp movedoc 
status = %d, version = %d\n", ok, vers); 
[* 


The following line uses the UNIX free command to 
deallocate the memory set aside for the document 
* 
/ 
free(iDocName); 
if (ok) exit( 1); 


} 

/* 

The following lines show the code for createTable. 
createTable is the routine that actually creates the table. The 
units of measurement are in micas, where 1 mica = 1/100 
mm | 
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st 

#include <stdio.h> 

#include <malloc.h> 

#include “DoclCProps.h" 

#include “DocliC.h" 

#include "“TablelC.h" 

[* 

The following lines define the table to have two columns, 
and two rows 


* 

/ 
#define COLUMN NUM 2 
#define ROW NUM 2 
ha _ 


The following lines define the caption to appear at the 
bottom of the table 
* 
/ 
#define WTCAP FALSE 
#define WBCAP TRUE 
#define WLCAP FALSE 
#define WRCAP FALSE 
/* 
The following line is used indi apaframe and specifies that 
the frame will be adjusted to fit the existing frame 
* 
/ 
#define TRSTS FALSE 


extern int error display() 


int createTable(doc, ret) 


di doc *doc; 
ret apaframe “ret; 
{ 

inti, ok; 


di tconttCont; 

dp fontprops *afoprops = NULL; 
dp frameprops frameRec; 

ti tableprops propsRec; 

ti colinfoseq collnfoSeq; 

ti rowcontseq rowContSeq; 

ti handleret h; 

ret ftret_ finTable; 


tCont.type = TC DOC; 
tCont.h.doc = *doc; 
/* 
The following lines allocate memory for the table columns 
and rows 
ad | 
collnfoSeq.seq = (ti colinforec*) 
malloc (sizeof (ti colinforec) * COLUMN NUM); 
if (collnfoSeq.seq = = NULL) error display ("Malloc", 
1); 
rowContSeq.rowdat = (ti rowent 
*)malloc (sizeof (ti rowent) * COLUMN NUM); 
if (rowContSeq.rowdat = = NULL) { _ 
free(collnfoSeq.seq); 
error display("Malloc”, 1); 
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}; 
/* 


The following lines retrieve the default properties of an 
anchored frame to which the table will be placed 
*/ 
if(dp getframedef(&frameRec)) { 
- free(collnfoSeq.seq); 
free(rowContSeq.rowdat); 
error display("GetFrameDefault", 0); 


}: 
/* 


The following lines set the frame top margin to 18, and the 
frame bottom margin to 36 micas 
* 
/ 
frameRec.tmgn = 18; 
frameRec.bmgn = 36; 
[* 
The following lines get the default properties for the table 
* 
/ 
if(ti__gettablepropsdef(&propsRec)) { 
free(collnfoSeq.seq); 
free(rowContSeq.rowdat); 
error display("GetTablePropsDef" 0); 


}: 
/* 


The following line defers the table frame to the next page if 
it cannot fit on the current page 
*/ 

propsRec.deferon = TRUE; 
/* 
The following lines set the amount of white space above and 
below each header element to 329 micas and the line for the 
table to two pixels in width 


*/ 
propsRec.thdmgn = 329; 
propsRec.bhdmgn = 329; 
propsRec.dvrline.width = LW W2; 
‘hi — 


The following line sets the default column property 
definitions for the table 


*] 
if (ti getcolinforecdef(colinfoSeq.seq)) { 
~ free(colinfoSeq.seq); 
free(rowContSeq.rowdat); 
error display("GetCollnfoRecDef", 0); 
}; 
/* 


The following lines set the column to have a width of 3000 
micas, the left and right margin to 150 micas, and to be 
subdivided into two columns 


*/ 
collnfoSeq.seq->width = 3000; 
collnfoSeq.seq- >Imgn = 150; 
colinfoSeq.seq->rmgn = 150; 
colinfoSeq.length = COLUMN NUM; 
/* 
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The following line assigns each column in the table to the 
properties defined above | 


*/ 


for(i = 1;i< COLUMN NUM; i+ +)*(collnfoSeq.seq + 
i) = *collnfoSeq.seq; 
/* 
The following lines set the default row property definitions 
for the table 


al 
if(ti getrowentdef(rowContSeq.rowdat)) { 
~~ free(colinfoSeq.seq); 
free(rowContSeq.rowdat); 
error display("GetRowEntDef", 0); 
}i 
/* 


The following lines set the top and bottom margin to 139 
micas, a solid line two pixels in width, text alignment is 
centered within each row, and the number of rows to two 
at | 
rowContSeq.tmgn = 139; 
rowContSeq.bmgn = 139; 
rowContSeq.line.style = LS SOLID; 
rowContSeq.line.width = LW W2; 
rowContSeg.valign = VA FCENTER; 
rowContSeq.length = ROW_ NUM; 
[* 
The following line assigns each row in the table to the 
properties defined above 


* 
/ 
for(i = 1; 1 <ROW NUM; i+ +) 
*(rowContSeq.rowdat + i) = 
*rowContSeq.rowdat; 
/* 


The following lines create a table with the properties 
defined by &propsRec and &colinfoSeq 


*/ 
if(ti starttable(*doc, &propsRec, &collnfoSeq, &ret h)) 
ties Be 
free(collnfoSeq.seq); 
free(rowContSeq.rowdat); 
error display("StartTable”, 0); 
}: 
/* 


The following lines add rows to the table. The rows will have 
contents as defined by &rowContSeq 


*/ 
for(i = 0;i< ROW NUM;i+ +) 
if(ti appendrow (ret h, &rowContSeg)) { 
~ free(colinfoSeq.seq); 
free(rowContSeq.rowdat); 
error display(" Append Row", 0); 
}i 
/* 


The following lines use the UNIX free function to free the 
memory allocated to the table columns and rows 
*/ 
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free(collnfoSeq.seq); 
free(rowContSeq.rowdat); 


/* 
The following line finalizes the table creation 
* 
/ 
if(ti_ finishtable(ret_h, &ret__ finTable)) 
error display("FinishTable", 0); 
/* a 


The following line appends the anchored table frame to the 
text container &tCont. 


*/ 
ok = di apaframe(&tCont, AF_ TABLE, &frameRec, 
ret finTable.table, WTCAP, WBCAP, WLCAP, 
WRCAP, afoprops, TRSTS, ret); 
/* 
The following lines release the caption resources previously 
allocated 
af 
if (WTCAP) di_relcap(&ret->tcap); 
if (WBCAP) di_relcap(&ret- >bcap); 
if (WLCAP) di_relcap(&ret->Icap); 
if (WRCAP) di_relcap(&ret->rcap),; 
return (ok); 
} 


The ti__enumtable() function reads the contents of a table. 
ti__enumtable() takes as arguments an instance of a table, 
di__ins, and three call-back procedures: 


ti__ tableproc() 
ti__ columnproc() 
ti__rowproc() 


ti__enumtable() will call ti_tableproc() and ti_.columnproc() 
once while enumerating a given table. These call-back 
procedures obtain the table and column properties. Since the 
table contents are stored in the row properties, ti_enumtable() 
will call ti_rowproc() once for each row in the table. 


Example of enumerating tables 


#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include §<doctk/DociCProps.h> 
#include §<doctk/DociC.h> 
#include §<doctk/Desktop.h> 
#include <doctk/Signals.h> 
#include <doctk/XString.h> 
#include <doctk/TablelC.h> 


ti__stop tableproc(); 
ti stop rowenum(); 
ti__ stop gettableprops(); 
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ti stop getcolumnprops(); 
dp bool readtext(); 

void errorexit(); 

int micatospace(); 

dp bool paraproc(); 

dp bool addtexttofile(); 
void printhorizontalline(); 


struct cdata { 

FILE *fp; 

di docdoc; 

ti tableprops *tableprops; 

ti colinfo colprops; 

int curcol, currow, *tablewidth; 


}; 


main(argc, argv) 
int argc; 
char *argv{]; 


char *ascii; 

XString docname; 

ret openreto; 

di tcont tcont; 

di enumprocs docenums; 
dp bool stop; 

unsigned short vers; 

dsktp docref ref; 

struct cdata *mydata; 


{* 
The following lines allocate memory to hold the client data 
*] 
if ((mydata = (struct cdata *)malloc (sizeof(struct cdata))) 
= = NULL) { 
fprintf (stderr, “Malloc error\n"); 
exit (-1); 
} 
/* 


The following lines initialize the table row and column 
pointers and properties 
*/ 
mydata->curcol = 0; 
mydata->currow = -1;/* row0 = header*/ 
mydata->tablewidth = NULL; 
mydata->colprops = NULL; 
mydata->tableprops = NULL; 
/* 
The following lines check that a document name was given 
during the invocation of this program 
*/ 
if (argc! = 3) { 
fprintf(stderr, "You must provide a name for the 
document and output file i.e. the correct form is 
%s docname outputfile\n", argv[0]); 
exit(1); 
} 
/* 
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The following line gets the document name from the 
invocation argument, and allocates memory for the 
document 


*/ 
ascii = argv[1]; 
if ((docname = (XString)malloc((strien(ascii) + 1) * 2)) 
= = NULL) { 
fprintf(stderr, “Malloc error\n"); 
exit(-1); 
} 
/* 


The following line converts the ASCII file name into an 
XString and stores it in the variable docname 
* 
/ 
XStrfromASC(docname, ascii); 


vers = 1; 
[* 
The following line retrieves the document from the desktop 
* 
/ 
if(dsktp _getdocref(docname, vers, NULL, ref)) 
errorexit (NULL, NULL); 
/* 
The following lines open the document, and print an error if 
problems occur while opening the document 
*/ 
if(di__open(ref, &reto)) errorexit(NULL, NULL); 


if (reto.status!= OP OK) { ; 

fprintf (stderr, "Problem opening named document\n"); 
exit (1); 

} 


mydata->doc = reto.doc; 
/* 
The following lines create a UNIX ASCII output file to contain 
the enumerated table 


*/ 
if ((mydata->fp = fopen(argv[2], "w")) = = NULL) { 
fprintf(stderr, "Can't open file called %sn", 
argv[2)); 
di close(&reto.doc); 
exit( 1); 
} 
/* 


The following lines set the text container type to bea 
document, and the text container handle to be reto.do 
a 
tcont.type = TC DOC; 
tcont.h.doc = reto.doc; 
/* 
The following line sets all elements of di enumprocs to NULL 
*/ = 
if(di_getenumprocsdef(&docenums )) 
errorexit(&reto.doc, mydata- > fp); 
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* 


The following line sets the call-back procedure for an 
anchored frame to be tableproc 
* 
/ 
docenums.aframe = tableproc; 
[* | 
The following lines enumerate the document using the call- 
back procedures defined in docenums. No page numbering 
patterns will be included in the heading or footing as 
indicated by the FALSE value for mrgnum. 
* 
/ 
if(di_ enumerate(&tcont, &docenums, mydata, FALSE, 
&stop)) errorexit(&reto.doc, mydata-> fp); 
/* 
The following lines finalize the document and close it 
* 
/ 
if(di__close(&reto.doc)) errorexit(NULL, mydata-> fp); 


if (fclose(mydata->fp)) { 
fprintf(stderr, “Problem closing text file\n"); 


exit( 1); 
} 
fprintf (stdout, "finished reading table\n"); 
} 
/* 


The following routine is tableproc, and is the main program 

for enumerating a table 

*/ 

ti stop tableproc(cdat, type, font, frame, props, cont, tcap, 
~~ beap, Icap, rcap) 

void (*cdat); 

di aframetype type; 

dp fontprops *font; 

di ins frame; 

dp frameprops * props; 

di ins cont; 

di caption tcap; 

di caption bcap; 

di caption Icap; 

di__caption rcap; 


{ 
ti_enumprocs tableenumprocs,; 
struct cdata *mydata; 
mydata = (struct cdata *)cdat; 
/* 


The following line returns to the main program if the type 
encountered is not an anchored table frame 
*/ 
if(type!= AF TABLE) return(FALSE); 
/* i 
The following lines define the call-back procedures for the 
table, column, and row enumeration procedures 
*/ 
tableenumprocs.table = gettableprops; 
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tableenumprocs.column = getcolumnprops; 
tableenumprocs.row = rowenum; 
/* 
The following line enumerates the table using the call-back 
procedures defined in tableenumprocs 
i 
if(ti enumtable(cont, &tableenumprocs, mydata)) 
return(TRUE); 


printhorizontalline(mydata, FALSE); 
return(FALSE); 


} 


/* 
The following routine, gettableprops, retrieves the table 
properties and places them into mydata- >tableprops 
* 
/ 
ti__ stop gettableprops(cdat, props) 
void *cdat; 
ti__tableprops “props; 


/* 
The following lines assign the table properties to the client 
data structure, and initialize the table properties 
* 
/ 
struct cdata *mydata; 
mydata = (struct cdata *)cdat; 
mydata->tableprops = NULL; 
/* 
The following line allocates memory to hold the table 
properties 
*/ 
if ((mydata->tableprops = (ti__tableprops *) 
malloc (sizeof(ti__tableprops))) = = NULL) { 
fprintf(stderr, “Malloc error\n"); 
exit(-1); 


} 
/* 


The following line adds the table properties as defined by 
*props to the client data structure *mydata-> tableprops 
* 
/ 
*mydata->tableprops = *props; 


return(FALSE); 
}; 


[* 

The following routine, getcolumnprops, retrieves the table 
column properties and places them into the client data 
structure 

*/ 

ti stop getcolumnprops(cdat, columns) 

void (*cdat); 

ti__colinfo columns; 


{ 
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inti; 

struct cdata *mydata; 

di tconttcont; 

di enumprocs hdrenums; 
dp boolstop = FALSE; 
char *hdrstring = NULL; 

int vpcolwidth, unixcolwidth; 


mydata = (struct cdata *)cdat; 


/* 
The following lines allocate memory for the table column 
properties 
*/ | 
if ((mydata->colprops = (ti colinfoseg *)malloc 
(sizeof(ti colinfoseq))) = = NULL) { 
fprintf(stderr, "Malloc error\n"); 
return(TRUE); 
} 
mydata->colprops->length = columns->length; 
mydata->colprops->seq = NULL; 
/* 


The following lines allocate memory for the data stored 
within the columns as well as the table width 


3 
if ((mydata->colprops->seq = (ti colinforec *) malloc 
(sizeof (ti colinforec)*columns->length)) = = 
NULL) { fprintf(stderr, “Malloc error\n"); 
return(TRUE); 
} 
if ((mydata->tablewidth = (int *)malloc(sizeof(int) * 
columns->length)) = = NULL) { 
fprintf(stderr, “Malloc error\n"); 
return(TRUE); 
} 
/* 


The following lines copy the column properties plus convert 
the column widths to characters and store it in the main data 
structure 
a | 

for (i = 0;i < columns->length; i+ +) { 


if (columns- >seq[i].divid) { 
fprintf(stderr, "Divided columns not supported, 
operation aborted\n’); 
return(TRUE); 


} 


mydata->colprops->seaq[i] = columns->sea[i]; 
/* 
The following lines get the column widths in characters and 
put them into the array in the main data structure 
eh 
vpcolwidth = mydata->colprops- >seq[i].width; 


if (micatospace(vpcolwidth, &unixcolwidth) ) 
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return(TRUE); 


mydata->tablewidth[i] = unixcolwidth; 


} 
/* 


The following lines print a horizontal line to separate the 
header from the table contents 
*] 

printhorizontalline(mydata, FALSE); 

putc(‘|', mydata-> fp); 
/* 
The following lines set the type to be text and set all 
elements of di _enumprocs to NULL 


*/ 
tcont.type = TC TEXT; 
if(di_getenumprocsdef (&hdrenums)) return(TRUE); 
hdrenums.text = readtext; 
for (i = 0;i < columns->length; i+ +) { 
tcont.h.text = mydata-> colprops- > 
seq[i].hdentry.cont.u.text; 
mydata->curcol = i; 
/* 


The following lines enumerate the header information 
a 
if(di_ enumerate(&tcont, &hdrenums, &hdrstring, 
FALSE, &stop)) return(TRUE); 
/* 
The following lines print the header text in the ASCII output 
file 
*/ 
if (addtexttofile(hdrstring, mydata)) return(TRUE); 


} 
/* 


The following line places a newline character into the ASCII 
output file 
*/ 
putc(‘\n', mydata-> fp); 
return(FALSE); 
} 
/* 
The following routine, rowenum, enumerates the table rows 
and prints the row contents to the ASCII output file 
*/ 
ti__ stop rowenum(cdat, cont) 
void (*cdat); 
ti__rowcont cont; 


{ 


di enumprocs rowenums; 
dp bool stop; 

inti, j, k; 

struct cdata *mydata; 
di_tcont tcont; 
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char *curstring = NULL; 
int vocolwidth, unixcolwidth, len; 


mydata = (struct cdata *)cdat; 


tcont.type = TC TEXT; 
i* | 
The following line sets all elements of di enumprocs to NULL 
*/ a 
if(di getenumprocsdef (&rowenums)) return(TRUE); 
/* a 
The following lines identify the call-back procedures 
readtext and paraproc for the row enumeration process 
st 
rowenums.text = readtext; 
rowenums.newpara = paraproc; 
| has 
The following line prints a horizontal line in the output ASCII 
file to separate the row 
* 
/ 
printhorizontalline(mydata, TRUE); 
putc('|', mydata- > fp); 
/* 
The following lines go through the row column by column 
and enumerates the textual content of each cell 
* 
/ 
for(i = 0; i < cont->length; i+ +) { 


mydata->curcol = j; 
tcont.h.text = cont->rowdat[i].cont.u.text; 


if (di enumerate(&tcont, &rowenums, &curstring, 
FALSE, &stop)) 
return (TRUE); 
/* 
The following line adds the row contents to the output ASCII 
file 
*/ 
if (addtexttofile(curstring, mydata)) return (TRUE); 
} 
/* 


The following line adds a newline character to the output 
ASCII file 
*/ 

putc (‘\n', mydata- > fp); 

mydata->currow + +; 


return(FALSE); 
} 
/* 
The following routine, readtext, reads the table contents 
into the ASCIl string passed in cdat 


ey 


dp bool readtext(cdat, foprops, text) 
void (*cdat); 

dp__fontprops *foprops; 

XString text; 
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{ 
char **curstring, *ascil; 
char dummy = '?'; 
curstring = (char **)cdat; 
/* 
The following lines allocate memory to hold the text string 
| 
if ((ascii = (char *)malloc(XStrien(text) + 1)) = = NULL) { 
fprintf(stderr, “Malloc error\n"); 
exit (-1); 
} 
XStrtoASC(text, ascii, dummy); 
if (*curstring = = NULL) 
*curstring = ascil; 
else { 
/* 


The following lines allocate more memory since an existing 
string is being appended to 


*/ 
*curstring = (char *)realloc (*curstring, strien 
(*curstring) + strien(ascii) + 1); 
strcat(*curstring, ascil); 
} 
return(FALSE); 
} 
j* 


The following routine, addtextofile, writes text to the 
output ASCII file 

*/ 

dp bool addtexttofile(text, mydata) 

char *text; 

struct cdata *mydata; 


{ 


intlen, colwidth; 


colwidth = mydata->tablewidth[mydata->curcol]; 
/* 
The following lines check the length of the text string, and 
truncates the text string if it is longer than the column width 
*/ 
if ((len = strlen (text)) > = colwidth) { 
fprintf(stdout, “The cell content in column %d, 
row %d istoolong for cell width. The text 
has been clipped\n", mydata->curcol + 1, 
mydata->currow + 1); 
text[colwidth] = ‘\0'; 
} 


fprintf(mydata->fp, "%-*s|", colwidth, text); 
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if (len > 0) £ 
free(text); 
text = NULL; 
Pics 
return (FALSE); 
} 
/* 


The following routine, paraproc, does nothing, but it makes 


sure that FALSE is returned from the enumerate procs 
* 
/ 
dp __bool paraproc(cdat, foprops, prprops) 
void (*cdat); 
dp __fontprops *foprops; 
dp paraprops *prprops; 
= 


return (FALSE); 


/* 

The following routine, errorexit, is a general routine for 
printing error messages and exiting when an error is 
encountered 

a 

void errorexit(vpdoc, unixdoc) 

di doc *vpdoc; 

FILE *unixdoc; 


fprintf(stderr, “Error reading table: signo = 
%x\n" ,getsigno()); 


if(vpdoc!= NULL) di close(vpdoc); 
if (unixdoc ! = NULL) fclos (unixdoc); 


exit(1); 


} 

/* 

The following routine, printhorizontalline, prints a 
horizontal line in the output ASCII file to separate rows, 
headers, etc. 

*/ 

void printhorizontalline(mydata, withvert) 

struct cdata *mydata; 

dp bool withvert; 

p= 


inti,}; 
if (withvert) putc('|', mydata->fp); 
else putc('-', mydata->fp); 


for (i = 0;i < mydata->colprops->length; i+ +) { 
for (j = 0; | < mydata->tablewidth[i]; j + +) 
putc('-', mydata-> fp); 


if (withvert) putc('|', mydata-> fp); 
else putc('-', mydata->fp); 
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putc(‘\n', mydata->fp); 


/* 

The following routine, micatospace, converts the width in 
micas into the width in characters. This is not accurate and is 
shown here merely as an example. 

ad 

Int micatospace(mica, space) 

int mica, *space; 


{ 
if (mica < = 0) return(-1); 
else *space = mica/214; 
return(Q); 

} 





Linking programs with the Document Interfaces Toolkit library 


Typically, document-specific programs generated with the 
Document Interfaces Toolkit will only need to be linked with the 
libdoctk.a library. An example of a makefile is shown below: 


#File:MyProgram.mk 


CC = cc-g $(CFLAGS) 
T = MyProgram 
TOOLKITLIB = /usr/new/lib/libdoctk.a 


all: program 
program: $(T) 


$(T): $(T).c 
$(CC)$(T).c $(TOOLKITLIB) -o $(T) 


#end of Makefile 


You will need to include the appropriate header files in your 
program. The Document interface library section of this manual 
lists the header files and which functions are associated with each 
header file. 





Document interface function calls 


di__abort() 
di__apaframe() 
di__apbreak() 
di__apchar() 


DOCUMENT INTERFACES TOOLKIT USER GUIDE 


An alphabetical listing of all functions provided by the Document 
Interfaces Toolkit specific to documents is listed below. 


terminate the document generation process 
append an anchored frame 
append a page break character 


append one or more instances of a specified text character to a 
string 
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di__apfield() 
di__apfntile() 
di__apfstyle() 
di__apindex() 
di__apnewpara() 
di__appfc() 
di__appstyle() 
di__aptext() 
di__aptofillin() 
di__aptotxtInk() 


di__clearfillin() 


di__cleartxtInk() 
di__close() 
di__enumerate() 
di__enumfillin() 
di__enumstyle() 
di__enumtxtlnk() 
di__finish() 
di__getfieldfromname() 
di__ getfnprops() 
di__getmode() 


di_open() 


di_relcap() 
di__relfield() 
di_ relfoot() 
di_ relhead() 
di__ relindex() 
di_ relnum() 
di__reltext() 
di__setfnprops() 
di__ setmode() 


di__setpara() 


di__start() 
di__startap() 


di__ starttext() 


append a document field 

append a Footnote Reference Tile 

append font properties to the styles in a document 

append an index character 

append one or more new paragraph characters 

append a page format character 

append paragraph style properties to the styles in a document 
append the text string specified 

append an item to the fill-in order of fields and tables 

append an item to the end of the text frame link order 


cancel the previously specified fill-in order for the entire 
document 


clear the text frame link order of a document 

release the document handle of a document being enumerated 
parse the contents of a document 

enumerate the fill-in order of fields and tables 

enumerate all the font and paragraph style rules in a document 
enumerate the link order of a text frame 

finalize a document 

search for a named field and list the properties of that field 
obtain the footnote properties of a document 

get the mode of properties for a document 

open a file 

release caption resources 

release field resources 

release footer resources 

release header resources 

release index resources 

release number resources 

release text resources 

set the footnote properties of a document 

set the mode properties of a document 


modify the paragraph properties of paragraphs in a specific text 
container 


initiate the document generation process 


acquire a file handle for appending information to an existing 
document 


initiate the process of appending text to the body of an 
anchored text frame 
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di__textforaframe() 
dp__colfromname() 


dp__enumfrun() 


dp__getbaspropsdef() 
dp__getbreakdef() 
dp__getcolwidthdef() 
dp__getfielddef() 
dp__getfnnumdef() 
dp__getfontdef() 
dp__getfontelmarralltrue() 
dp__getfontstyledef() 
dp _getframedef() 
dp__getindexdef() 
dp__ getmodedef() 


dp__getpagedef() 


dp__getpagedel() 
dp__getrundef() 
dp__gettabstopdef() 
dp__getparaelmarralltrue() 
dp__getparadef() 
dp__getparastyledef() 
dp__gettframedef() 
dp__gettoc() 


dp__namefromcol() 


dp__wkcolfromcol() 
dsktp__checkuser() 
dsktp__copydoc() 


dsktp__deletefolder() 
dsktp__deletedoc() 


dsktp__enumerate() 


dsktp__getaccess() 
dsktp__getdocref() 
dsktp__getdocpropsref() 
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extract text from an anchored frame during enumeration 
retrieve the integer equivalent of a well-known color 


perform an action defined by the client for each fontrun in an 
XString 


get default basic properties 

get the default properties of page break objects 
get the default column width properties 

get the default properties of a field 

get the default footnote numbering properties 
get the default font properties 

initialize all font element properties to TRUE 
get the default font style properties 

get the default anchored frame properties 

get the default index properties 


get the default properties of the commands in the document and 
auxiliary menus of a VP document 


retrieve the default properties associated with a specific page in a 
VP document 


get the default properties of the page number delimiter 
get the default fontrun properties 

get the default tab stop as follows 

initialize all paragraph element properties to TRUE 

get the default paragraph properties 

get the default paragraph style properties 

get the default text frame properties 

get the default table of content character properties 


retrieve the name of a color based upon the data that defines the 
well known color 


retrieve a well known color from color 
verify the identity of a user accessing the Desktop 


copy a document and return a reference, or pointer, to the 
duplicate document 


remove a folder from within another folder or from the desktop 


remove a document from within a folder, a nested folder, or on 
the desktop 


enumerate the documents in a folder, a nested folder, or on the 
desktop 


ascertain the status and access permissions of the Desktop 
acquire a reference, or pointer, to a document on a desktop 


obtain the properties of a document on the Desktop 
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dsktp__makefolder() 
dsktp__movedoc() 


getsigno() 
gi__adbacht() 
gi_adbm() 
gi__adcurve() 
gi__adellipse() 
gi__adffield() 
gi_adline() 
gi_adincht() 
gi__adpicht() 
gi__adpislce() 
gi_adpoint() 
gi__adrectangle() 
gi__adtable() 
gi__adtframe() 
gi__adtriangle() 
gi__apchartobtnprog() 
gi__apnparatobtnprog() 
gi__aptexttobtnprog() 


gi__btnforaframe() 


gi__enumbtnprog() 
gi__enumerate() 
gi__finishbtn() 
gi__finishcht() 


gi__finishcluster() 
gi__finishgframe() 
gi__finishgr() 
gi__finishnbtn() 


gi__getbachtpropsdef() 
gi__getbmdispdef() 
gi__getbmpropsdef() 
gi__getbmscalpropsdef() 


create a folder on the desktop or within an existing folder on the 


desktop 


move a document to a folder, to a nested folder, or onto the 


desktop 

retrieve the number of an error 

add a bar chart to a graphic container 

add a bitmap graphic to a graphic container 
add a curve to a graphic frame 

add an ellipse to a graphic container 

add a form field to a graphic frame 

add a line to a graphic container 

add a line chart to a graphic container 

add a pie chart to a graphic container 

add a pieslice object to a graphic container 
add a point to a graphic container 

add a rectangle to a graphic container 

add a table frame to a graphic container 
add a text frame to a graphic container 
add a triangle to a graphic container 


add a character to a CUSP button program 


add a new paragraph to a CUSP button program 


add a string to a CUSP button program 


extract the properties of a button in an anchored CUSP button 


frame during enumeration 


enumerate the properties and text contents of a CUSP button 


read the contents of a graphics frame 


terminate the creation of an anchored button 


indicate that no more objects are to be added to a chart 


indicate that no more objects are to be added to a cluster and 
free the allocated resources 


indicate that no more objects are to be added to a graphic 


container 


indicate that no more objects are to be added to a graphic 
container and free the allocated resources 


indicate that no more objects are to be added to a graphic 
container and free the allocated resources 


get default bar chart properties 

get default bit map display properties 
get the default bit map properties 

get the default bit map scale properties 
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gi_ getboxdef() 

gi_ getchtappdef() 

gi_ getchtdatdef() 

gi__ getcurvepropsdef() 
gi__ getellipsepropsdef() 
gi__getframepropsdef() 
gi__getgframeprops() 


gi_ getgframepropsdef() 
gi_ getgridpropsdef() 
gi_ getlinepropsdef() 
gi_ getInchtappdef() 

gi__ getinchtpropsdef() 
gi__ getpichtpropsdef() 
gi_ getpisicepropsdef() 
gi_ getpointpropsdef() 
gi_ getrectanglepropsdef() 
gi__gettframepropsdef() 
gi_ gettrianglepropsdef() 
gi_relbtnprog() 


gi__setgframeprops() 
gi_startbtn() 
gi__startcluster() 
gi__startgframe() 
gi__startgr() 
gi__startnbtn() 
ti_appendrow() 
ti_deffont() 
ti__defpara() 
ti__enumtable() 
ti_finishtable() 
ti__getcolinforecdef() 
ti_gethdentrydef() 
ti_ getlinedef() 
ti__getrowentdef() 
ti_ getsortkeydef() 
ti__gettablepropsdef() 
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get the default box properties 

get the default chart appearance properties 
get the default chart data properties 

get the default curve properties 

get the default ellipse properties 

get the default frame properties 


retrieve the name, description, and grid properties of an 
anchored graphic frame 


get the default graphic frame properties 
get the default grid properties 

get the default line properties 

get the default line chart appearance properties 
get the default line chart properties 

get the default pie chart properties 

get the default pie slice properties 

get the default point properties 

get the default rectangle properties 

get the default text frame properties 
get the default triangle properties 


release handles obtained by calls to gi__startbtn() or 
gi__startnbtn() 


set the properties of a graphics frame 

create an anchored CUSP button 

create a graphic cluster 

nest a graphic frame within a graphics container 
create a graphic frame in a document 

create a CUSP button in an anchored frame 

add a row to a table 

assign default font property values to table elements 
assign default paragraph property values to table elements 
parse the contents of a table 

close table being edited 

get default column properties 

get default header entry properties 

get default line properties 

get default row properties 

get default sort key properties 

get default table properties 
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ti__gettableprops() 


ti__ maxelm() 


ti__startextable() 
ti__starttable() 
XCharcode() 
XCharmake() 


XCharset() 
XStrcasecmp() 
XStrchr() 


XStrcaselexcmp() 


XStrcat() 
XStrcmp() 
XStrcpy() 
XStrdup() 


XStrfromASC() 
XStrfromXxCCa() 
XStrlen() 
XStrlexcmp() 


XStrncasecmp() 
XStrncaselexcmp() 
XStrncat() 
XStrncmp() 
XStrncpy() 
XStrnlexcmp() 
XStrpbrk() 
XStrrchr() 


XStrsch() 
XStrsep() 


extract the properties of a named table 


estimate the maximum number of cells that may be added to a 
table in a document 


prepare table to receive new data 
add a new table to a document 
retrieve the XChar character code (the lower 8 bits) 


create characters having specific visual qualities, based upon the | 
character set defined in the Xerox Character Set Standard and the 
character codes defined in Xerox Character Code Standard 


retrieve the XChar character set (the higher 8 bits) of a character 
compare two strings, while ignoring the case of ASCII characters 
parse a string in search of a specific character 


compare two strings, while ignoring the case of ASCII characters 
and while sorting the character strings in the order specified in 
sortorder 


concatenate one string to the end of another string 
compare two strings 
copy a specific string into a VM storage area 


copy a text string into a storage area and return a pointer to that 
area 


convert an ASCII string to an XString 

convert an XCCS 8-bit encoded string into an XString string 
determine the logical length of an XString character 
compare two strings according to a sort order 


compare a portion of one string against another string, while 
ignoring the case of ASCII characters 


compare a portion of one string against another string, while 
ignoring the case of ASCII characters 


copy a specific number of characters from one string and append 
them to the end of another string 


compare a portion of one string against another string 
copy a specific number of characters in a text string 


compare two strings, while ignoring the case of ASCII characters 
and while sorting the character strings in the order specified in 
sortorder 


search a string for the occurrence of any character contained 
within another string 


search for a character within a string, starting from the end of the 
string and proceeding forward towards the beginning of the 
string 


determine if a string is contained within another string 


separate a string into tokens based upon one or more delimiter 
characters 
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XStrtoASC() convert the XString into an ASCII string 
XStrtoXCC&() — convert an XString into a compact XCCS 8-bit encoded string 
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di__abort() 


di__apaframe() 
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a 
5. Document function examples 


This chapter present example code fragments for the document- 
specific functions to illustrate their usage. Only the major 
functions have been listed. See chapter 4 for more detailed 
examples for creating and enumerating documents, tables, and 
graphics. Consult the Document Interfaces Toolkit Reference 
Manual for a complete description of all the available XNS 
functions. 


The examples are organized alphabetically and have the following 
format: 


Function name 

Function brief description 
Function syntax 

Example code fragment 
Description of the example 


The di__abort() function is used to terminate the document 
generation process and deallocate the storage resources 
allocated to that document. 


di__abort(doc) 
Example 


if (ret.stat != SC_OK) { 
fprintf(stderr, "ret_scstatus = %d\n", ret.stat); 
if (di_abort(&ret.doc)) exit(-1); 
exit(1); 


} 


In the preceding example, the return status from a di_start() 
function is checked to see if the call returned successfully. If the 
status does not match SC__OK, then an error message will be 
printed, and the document generation process will be aborted. 
ret.doc is the file handle returned by the di__start() function, 
and is used by the di__abort() function to determine which 
document to finalize. 


The di__apaframe() function is used to append an anchored 
frame to a text container. 
di__apaframe(to, type, frame, cont, wtcap, wbcap, wlcap, 
wrcap, font, trustsize, ret) 


Example 


type = AF_TEXT; 
contents = "“Appending anchored text frame" 
if (di_apaframe(&to, type, NULL,contents, FALSE, TRUE, 
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di__apfield() 


di__aptext() 


FALSE, FALSE, NULL, FALSE, &anc_ret)) exit (-1); 


In the preceding example, an anchored text frame is appended 
to the document container specified by &to. type specifies the 
type of anchored frame to be appended, and contents specifies 
the contents to be appended. In this example, type is defined 
as AF__TEXT or a text frame. Setting the argument frame to NULL 
specifies that the default dp__frameprops variables should be 
used. The arguments wtcap, wbcap, wlicap, and wrcap specify 
the location of the caption. In the above example, the caption 
will be placed at the bottom, as defined by the TRUE value of 
wbcap. anc__ret will return a handle to the caption so that its 
contents can be defined and appended. Setting font to NULL 
means that the anchored frame will have default font properties. 
Setting trustsize to FALSE means that the frame size specified by 
frame will be ignored and the frame will be adjusted to fit the 
existing frame. 


The di__apfield() function is used to append a document field to 
a text container. 


di__apfield(to, fiprops, foprops, ret) 
Example 


void (*cdat); 

dp fontprops *fontprops; 
dp fidprops *fieldprops; 
di tcont *to; 

di field ret; 


to = (di tcont*)cdat; 
if (di_apfield(to, fieldprops, fontprops, &ret)) return (TRUE); 


In the preceding example, a doc field is appended to a text 
container specified by to. The field and font properties are 
specified by fieldprops and fontprops, respectively. The default 
values for fieldprops and fontprops can be obtained through 
calls to the dp__getfielddef() and dp__getfontdef() functions. 
ret can be passed to other di__ap*() functions in order to add 
data to the appended field. 


The di__aptext() function is to append a text string to a text 
container. 


di__aptext(to, text, foprops) 
Example 


dp _ fontprops *foprops; 

charinsert string[256]; 

XString text to add; 

di tcont*to; 

insert string = “This is the Document Interfaces Toolkit User 
Guide" 


XStrfromASC(text to add, insert string); 
to = (di__tcont*)cdat; 
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di__aptofillin() 


di__close() 
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if (di_aptext(to, text, foprops)) return (TRUE); 


In the preceding example, the text string “This isthe Document 
Interfaces Toolkit User Guide” is appended to the text container 
specified by to. The text string is translated into an XString 
format through the XStrfromASC function.The font properties 
of the text string are specified by foprops. The default properties 
of foprops can be obtained through a call to dp_getfontdef(). 


The di__aptofillin() function is used to append an item to the 
fill-in order of fields and tables. 


di__aptofillin(doc, name, type) 
Example 


void (*cdat); 

char * insert_string = “Field1“; 
XString name; 

di_fillintype type; 

di_doc target; 


XStrfromASC(name, insert_string); 
type = FI_FIELD; 
target = (di_doc)cdat; 
if (di_aptofillin(target, name, type)) { 
error_display (“AppendTofFillin”, 0); 
return(TRUE); 
In the preceding example, the string specified by insert_string is 
appended to the fill-in order of the table specified by target. 
Fi_FIELD signifies that a field is the object whose fill-in order will 
be appended to. target is returned from an earlier call to either 
di_start() or di_startap(). If the di_aptofillin() function does 
not return successfully in the preceding example, the user- 
defined procedure error_display is then called. 


The di__close() function is used to release the document handle 
of an enumerated document. 


di__close(docptr) 
Example 


if (di_enumerate(&to, &procs, &data, mrgnum, &stops)) { 
error_display(“Enumerate”, 0); 
di_close(&ret.doc); 
exit(1); 

hi 


In the preceding example, the document specified by the 
document handle &ret will be closed if the di_enumerate() 
function does not return successfully. di__close() will release the 
document handle and free the storage space originally allocated 
to it. 
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di__enumerate() 


di__enumstyle() 


The di__enumerate() function is used to parse the contents of a 
document. 


di__enumerate(to, procs, cdat, mrgnum,ret) 
Example 


to.type = TC DOC; 

to.h.doc = ret.doc; 
data.source = ret.doc; 
mrgnum = FALSE; 

di getenumprocsdef(&procs); 
procs.text = textproc; 
procs.field = fieldproc; 
procs.index = indexproc; 


if(di_ enumerate(&to, &procs, &data, mrgnum, &stops)) { 


errorexit(); 
}: 


In the preceding example, the document specified by the 
document handle &to is to be enumerated. to.type has the value 
of TC__DOC, meaning that the text container is a document. 
The di_getenumprocsdef() function is used to set all elements 
of di__enumprocs to NULL so that the user can define the 
required call-back procedures. &procs defines the user-defined 
call-back procedures used to enumerate the document. In the 
above example, the call-back procedures textproc, fieldproc, 
and indexproc will be called when a text, field, and index object 
is encountered. If any of these call-back procedures returns a 
TRUE, then the enumeration process is halted. mrgnum has a 
value of FALSE, meaning that a page numbering pattern will not 
be included in the heading or footing during enumeration. 
&stops is a pointer to the user-defined data that is passed to the 
call-back procedures. &stops is set to TRUE if di_enumerate() 
encounters an object that it can not recognize, or if it encounters 
an object for which a client call-back procedure was not 
supplied. 


The di__enumstyle() function is used to enumerate all the font 
and paragraph style properties of a document, such as mode, 
fill-in order,and text-link. 


di__enumstyle(doc, fstyleproc, pstyleproc, cdat) 
Example 


di stylestyle; 

void (*cdat); 

di apfstyleproc (*fstyleproc); 
di _appstyleproc (*pstyleproc); 
{ 


myStyle mydat; 
myData *data; 


data = (myData *)cdat; 
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mydata.style = style; 

mydata.fstyleproc = fstyleprocedure; 

mydata.pstyleproc = pstyleprocecure; 

di enumstyle(data->source, fstyle callback, 
~ pstyle callback, &mydat); 


} 


In the preceding example, the font and paragraph style 
properties of the document specified by data->source will be 
enumerated. This document handle is obtained from an earlier 
call to di__open() or di__startap(). fstyle__callback and 
pstyle__callback are user-defined call-back procedures to be 
invoked once for each object in the style. If any of the call-back 
procedures returns TRUE, the enumeration will be halted. 


The di_setmode() function is used to set the mode properties 
of a document. 


di__setmode(doc, props, select) 
Example 


di doc source; 

di doc target; 

= 
dp _modeprops props; 
dp modesel select; 
unsigned int i; 


for (i=0;i< = ME PROMPT; i + +){ 
select[i] = TRUE; 
}: 


if(di_ getmode(source, &props)) return(-1); 


if(di_ setmode(target, &props, select)) return(-1); 
return(0); 


} 


In the preceding example, the mode properties of the document 
specified by the document handle target are set. Mode 
properties display the structure, non-printing characters, cover 
sheets, and prompt fields in a document. In the above example, 
the for statement defines which properties will be affected. 
Those properties which are designated by TRUE will be changed. 
di_ getmode() was called to get the default mode properties 
which can then be modified to suit the user’s needs. 
di__setmode() is then called to set the mode properties of the 
document. &props defines the display characteristics of the 
document. 


The di__start() function is used to initiate the document 
generation process. 
di__start(pagiops, whead, wfoot, wnum, tfoprops, 
iprprops, ipgprops, styledat, ret ) 
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di__starttext() 


dp__colfromname() 


Example 


if(di start(PO COMPRESS,TRUE, FALSE, FALSE, NULL, 
NULL, NULL, NULL, &ret)) £ 
printf("Errorindi start, getsigno = %x\n", getsigno()); 
exit(-1); _ 


}; 


In the preceding example, an empty document will be created 
with the following properties: compressed pagination, header 
properties inserted into the first page format character, no 
footing or numbering properties inserted into the first page 
format character, default initial font, paragraph, and page 
properties, default values for the first new paragraph and page 
format characters. The &ret handle can be passed to other 
di__ap*() functions to add information to the document. More 
information on default properties can be found in the Document 
Interfaces Toolkit Reference Manual. 


The di__starttext() function is used to initiate the process of 
appending text to the body of an anchored text frame. 


di__starttext(doc, frame, props, ret) 
Example 


di__text desttext; 
dp _gettframedef (&tframepropsref); 
if(di starttext(data- >target, ret.frame, &tframepropsref, 


&desttext)) { 
error display("Start Text”, 0); 
return(TRUE); 

}; 


In the preceding example, the text frame defined by the 
ret.frame is “readied” to accept new text. ret.frame is the 
frame handle returned by an earlier call to di__apaframe(). The 
properties of the text frame are defined by &tframepropsref, 
which in turn is defined by dp__gettframedef(). &desttext 
returns a handle which then can be passed to various di__ap*() 
functions to add the actual data. data->target is the document 
handle returned by an earlier call to di__start() or di__startap(). 
In the above example, if di__starttext() does not return 
successfully, then a user-defined procedure, error__display(), 
will return an error status. 


The dp__colfromname() function is used to retrieve the integer 
equivalent of a well known color. 


dp__colfromname(name, ret) 
Example 


ret__wkcolfromname retcolor; 
dp __fontprops foprops; 
dp color *color; 


if (dp __getfontdef(&foprops)) errorexit(); 
if(dp_colfromname(CL__GREEN, &retcolor)) errorexit(); 
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foprops.txtcol = retcolor.color; 


In the preceding example, the color of a text string is defined to 
be green. CL__GREEN defines the desired color, and &retcolor 
returns a structure whose member is an array of three integers 
that specifies the color green. This member is passed to 
foprops.txtcol to assign the text the color of green. A complete 
list of available colors is shown in the Document Interfaces 
Toolkit Reference Manual. 


The dsktp__movedoc() function is used to move a document to 
a folder, a nested folder, or the desktop. 


dsktp__movedoc(ref, dstpath, name, vers) 
Example 


ascii = argv[1]; 

name = (XString)malloc((strlen(ascii) + 1) *2); 
XStrfromASC(name, ascii); 

dsktp movedoc(&ret2.ref[0], NULL, name, &vers); 


In the preceding example, the document defined by its handle 
&ret2.ref[0], and its name, defined by name is moved to the 
desktop. A value of NULL for dstpath signifies that the document 
is to be placed onto the desktop, not a folder or a nested folder. 
The name of the document in this example was taken from the 
parameter argv[1] and translated into an XString format so that it 
may be understood by the GLOBALVIEW environment. 


The getsigno() function is used to determine the cause for the 
failure. 


getsigno() 
Example 


if(di start(PO COMPRESS, FALSE, FALSE, FALSE, NULL, 
NULL, NULL, NULL, &ret)) { 
printf("Errorindi start, getsigno = %x\n", getsigno()); 
exit(-1); _ 

}; 


In the preceding example, if di__start() does not complete 
successfully, then getsigno() is called to retrieve the error 
number returned by di__start(). The text description of the error 
number may be obtained through the Signals.h header file or the 
Document Interfaces Toolkit Reference Manual. 


The gi__apnparatobtnprog() function is used to add a new 
paragraph character to the button program. 


gi__apnparatobtnprog(to, paprops, foprops, num) 
Example 


void (cdat; 
dp__fontprops *foprops; 
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ti__appendrow() 


ti__getcolinforecdef() 


dp __paraprops *prprops; 


gi buttonprog to; 

to=(gi buttonprog)cdat; 

if(gi apnparatobtnprog(to, prprops, foprops, 1)) 
_ return(TRUE) 


In the preceding example, one new paragraph character is added 
to the CUSP button defined by its handle to. to is returned from 
an earlier call to gi__startbtn() or gi__startnbtn(). The properties 
of this new paragraph character is defined by prprops and 
foprops. These properties may be defined by calls to 
dp__getfontdef() and dp__getparadef(). num has the value of 1, 
meaning only one new paragraph character is to be added. 


The ti_appendrow() function is used to add a row to a table. 
ti__appendrow(h, rc) 

Example 
if (ti_ getrowentdef(rowContSeq.rowdat)) { 


} 


rowContSeq.tmgn = 139; | 
rowContSeq.valign = VA CENTER 
for(i = 0;i <ROW NUM;i+ +)if(ti appendrow(ret h, 
&rowContSeq)) £ _ _ 
free(collnfoSeq.seq); 
free(rowContSeq.rowdat); 
errorexit(); 
In the preceding example, the default row entry properties are 
retrieved, and then added to the table defined by the table 
handle ret__h. Information on retrieving default row entry 
properties can be found in the Document Interfaces Toolkit 
Reference Manual. ret__h may be obtained by an earlier call to 
either ti__starttable() or ti__startextable(). The number of rows 
to be added is defined by the parameter ROW__NUM. If the 
ti__appendrow() function is not successful, then the memory 
allocated to the column and row data is freed via the UNIX free 
command, and a user-defined errorexit() procedure is called. 


The ti__getcolinforecdef() function is used to get the default 
column properties. 


ti__getcolinforecdef(col) 
Example 


if (ti__getcolinforecdef(collnfoSeq.seq)) { 
errorexit(): 


} 
collnfoSeq.seq->width = 3000; 
collnfoSeq.seq- >Imgn = 150; 
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In the preceding example, the default column properties are 
retrieved and placed into the argument collnfoSeq.seq. This 
example also shows how some of the column properties may be 
modified from their default values. The width of the column, 
defined by collnfoSeq.seq- > width, has been changed to 3000 
micas. The left margin of the column, as defined by 
collnfoSeq.seq- >Imgn, is set to 150 micas. A complete list of 
default column properties is defined in the Document Interfaces 
Toolkit Reference Manual. 


The ti__getrowentdef() function is used to get the default row 
entry properties. 


ti_ getrowentdef(rowentry) 
Example 


if(ti__getrowentdef(rowContSeq.rowdat)) { 


errorexit(); 
} 
rowContSeq.tmgn = 120; 
rowContSeq.line.style = LS SOLID; 
rowContSeq.valign = VA_ CENTER; 


In the preceding example, the default row entry properties are 
retrieved and placed into the argument rowContSeq.rowdat. 
This example also shows how some of the row entry properties 
may be modified from their default values. The top margin, line 
style, and text alignment as specified by rowContSeq.tmgn, 
rowContSeq._line.style and rowContSeq.valign respectively, are 
changed. The top margin is set to 120 micas. The line separating 
the rows is defined to be a solid line. The text within each row 
will be centered. A complete list of default row entry properties 
is defined in the Document Interfaces Toolkit Reference Manual. 


The ti_gettablepropsdef() function is used to get default table 
properties. 


ti_ gettablepropsdef(props) 
Example 


if (ti gettablepropsdef(&propsRec)) £ 
free(colinfoSeq.seq); 
free(rowContSeq.rowdat); 
errorexit(); 


propsRec.bdrline = LW_ SOLID; 
propsRec.bdrline.width = LW W3; 
propsRec.dvrline.width = LW W2 


In the preceding example, the default table properties are 
retrieved, and are placed into the argument &propsRec. If the 
function call does not return successfully, then the memory 
allocated to the column and row properties are freed, as defined 
by the UNIX free command. errorexit() is a user-defined 
procedure in case of an unsuccessful return. The above example 
also shows how some properties may be changed. The table 
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border, propsRec.bdrline, and the divider line (the line between 
the header row and the rest of the table), prosRec.dvrline, are 
modified. The border line now has a solid line, and a width of 
three pixels. The divider line has been changed to have a line 
width of two pixels. A complete listing of the default table 
properties and their values can be found in the Document 
Interfaces Toolkit Reference Manual. 


ti__starttable() 


The ti__starttable() function is used to add a new table to a 
document. 


ti__starttable(doc, props, col, ret) 
Example 


if(ti starttable(*doc, &propsRec, &collnfoSeq, &ret h)) { 
free(collnfoSeq.seq); -_ 
free(rowContSeq.rowdat); 
errorexit(); 


}i 


In the preceding example, a table will be added to the document 
specified by the *doc document handle. The table properties 
are defined by the &propsRec argument. Default table properties 
may be obtained from the ti__gettablepropsdef() function, and 
later modified if required. &collnfoSeq defines the column 
properties for the table. The default column properties may be 
obtained from the ti__getcolinforecdef() function. The returned 
argument, &ret__h is a pointer to an opaque variable that 
contains the table handle. If the ti__starttable() does not return 
successfully in the preceding example, the memory allocated for 
the column and row data will be freed, and a user-defined 
procedure, errorexit(), will be called. 


XStrcat() 


The XStrcat() function is used to concatenate one string to the 
end of another string. 


XStrcat(xs1, xs2) 
Example 
ascii = ".CV" 
ext = (XString)malloc(strien(ascii) + 2) * 2); 


XStrfromASC(ext,ascil); 
name = XStrcat(name, ext); 


} 


In the preceding example, the string ".CV" is concatenated to 
the contents of name. Memory is allocated for ".CV" before it is 
translated to an XString format and later concatenated. The 
procedure for allocating memory is defined in the Document 
Interfaces Toolkit Reference Manual. 
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The XStrfromASC() function is used to convert an ASCII string to 
an XString. 


XStrfromASC(xs, s) 
Example 


ascil = "This is the Document Interfaces Toolkit User Guide"; 
name = (XString)malloc((strien(ascii) + 1)*2); 
name = XStrfromASC(name, ascii); 


In the preceding example, the string" This is the Document 
Interfaces Toolkit User Guide", defined by ascii, is converted to 
the XString name. Memory is allocated for the XString before 
XStrfromASC() is called. The procedure for allocating memory is 
defined in the Document Interfaces Toolkit Reference Manual. 
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6. XNS services 


This chapter presents guidelines for using the /ibxnstk.a library 
from the Document Interfaces Toolkit. It describes using the 
appropriate XNS header file, common XNS function arguments, 
handling courier errors, and special linking considerations. 


The XNS functions of the Document Interfaces Toolkit are not as 
order-dependent as the document-specific functions. Each XNS 
function calls a specific service request. This service request may 
be dependent on only one other call preceding it. As such, a 
generalized template cannot be generated for each task. 


This chapter will discuss the common elements of the XNS 
functions such as: the _ Connection and _ BDTprocptr 
argument found in all XNS functions, trapping for errors, linking 
procedures, and the recommended include files for each XNS 
service. Examples for the major XNS functions may be found in 
Chapter 7. 





XNS services header files 


The /ibxnstk.a library allows you access to the following XNS 
services: 


Printing 
Authentication 
Clearinghouse 
Gap 

Mailing 

Filing 


Each XNS service has two header files associated with it, 
[service]__de.h and [service].h, where [service] represents the 
name of the service, such as Printing3__de.h and Printing3.h. 
The [service]__de.h header files have define statements that 
eliminate the need for prefixing functions and error statements 
with the service name. [service].h is the "raw" header file. If you 
include the [service].h header file, you must prefix the name of 
the header file to each function or error name. Using the 
function Printing3__GetPrinterStatus as an example, 
Printing3__ is the prefix that you may or may not need to 
include. The following two examples compare these two 
approaches: 


If you include Printing3__de.h, you may use the following 
method of coding: 


# include "Printing3__de.h" 


StatusResult = GetPrinterStatus( 
getprintstatusconnected,NULL); 


switch (Exception.Code) { 


DOCUMENT INTERFACES TOOLKIT USER GUIDE 6-1 


XNS SERVICES 


case ServiceUnavailable: 
msg = "GetStat: Service unavailable"; 
break; 


If you include Printing3.h, your call to these same procedures 
must look as follows: 


# include "Printing3.h" 


StatusResult = Printing3_ GetPrinterStatus( 
getprintstatusconnected,NULL); 


switch (Exception.Code) { 

case Printing3__ServiceUnavailable: 
msg = "GetStat: Service unavailable"; 
break; 


In the second case, Printing3__ must precede both 
GetPrinterStatus and ServiceUnavailable. If, during 
compilation of your program, you encounter errors that report 
functions or error not found, you have probably included the 
wrong header file or you did not prefix your functions. 


Note that you should include either the [service]__de.h or the 
[service].h header file, but not both. 





__Connection and __ BDTprocptr parameters 


Every XNS function has two common parameters, _ Connection 
and _ BDTprocptr. 


The __ Connection parameter is the courier connection number 
for the XNS server the application is trying to reach. By using a 
particular number, a C application may, for example, talk to 
printer1 instead of printer2. This connection number may be 
obtained by using the following code in your C program: 


COURIERFD connected; 
char *hostnameptr; 


if (((connected = cour__establish__conn(hostnameptr))) £ 
fprintf(stderr, "\t\ttCOURIER CONNECTION FAILED!!! \n"); 
return; 


} 


In the above example connected is the return value of 
cour__establish__conn. cour__establish__conn is a function 
provided by the XNS basic software that checks the name of a 
specified pointer, hostnameptr in the preceding example. If the 
pointer is valid, then cour__establish__conn will try to connect 
to it. See the XNS for UNIX System V.3 Programming Guide for 
more information on this function. The hostnameptr parameter 
is a string that contains the name of the server you want to 
communicate with. You can now replace connected for 
__Connection in each applicable function. If the connection to 
the host does not occur, the above code will return an error 
message. | 
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The __ BDTprocptr parameter is the name of a function that 
performs the bulk data transfer. Bulk data is an arbitrarily long, 
ordered sequence of zero or more eight-bit bytes. Although any 
data may be modeled as bulk data, bulk data transfer is intended 
primarily for use in transporting objects that may be too large to 
be reasonably modeled as parameters or results of remote 
procedures. For example, directory listings and the contents of 
files are among the entities that may be modeled as bulk data. 
Not every XNS function requires the use of bulk data transfer. If a 
function does not require bulk data transfer, _BDTprocptr 
should be set to NULL. The following list shows the functions that 
require bulk data transfer: 


Clearing2__List() 
Clearing2__ListAliases() 
Clearing2__ListAliasesOf() 
Clearing2__ListDomains() 
Clearing2__ListDomainsServed() 
Clearing2__RetrieveMembers() 
Filing6__Desertalize() 

Filing6_ Serialize() 
Filing6__Store() 
Inbasket2__ChangeBodyPartsStatus() 
Printing3__Print() 
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The bulk data function must be created by you, the C 
programmer. For example, suppose you want to print an 
interpress document which resides in a UNIX directory. Your C 
code might contain the following XNS print call: 


printresult = Printing3__Print(printconnected, SendSource, 
BulkData1__immediateSource, attributes, options); 


For the purpose of explaining bulk data transfer, it is necessary to 
review the syntax for the print function used above. 


Printing3__ Print(__Connection, - BDTprocptr, master, 
printAttributes, printOptions); 


The second and third arguments, _ BDTprocptr and master, are 
the two parameters related to bulk data transfer. The master 
argument describes the bulk data type. It tells the function that 
data will be sourced from the UNIX environment or sinked into 
the UNIX environment. To specify source, set the value of 
master to be BulkData1__immediateSource. To specify sink, 
set the value of master to be BulkData1__immediateSink. The 
XNS print example above sourced data from the UNIX 
environment and therefore used BulkData1__immediateSource. 
__BDTprocptr is the name of your C program that sends print 
data from your UNIX environment to the XNS printer described 
by __Connection, the courier connection number. In the XNS 
print example above, “SendSource” is the name of the C 
program that sends the print data. An example of the 
SendSource program is shown below: 


int 

SendSource (bdtconnection) 
COURIERFD 

{ 

char * buf; 
int buflen; 
int count; 
extern int errno; 
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} 


int 
char 


len = 


len; 
local__buf[BUFSIZ]; 


sizeof(local__buf) < < 3; 


if(len <= 0 || !(buf = malloc(len))) £ 


buf = local__buf; 
len = sizeof(buf); 


while ((count = read(ipfile, buf, len)) > 0) { 


} 


if (cour__bdt__write(bdtconnection, buf, count) < 


count) { 
if (buf != local__buf) 
free(buf); 


return BDT__WRITE__ABORT; 
} 


if (buf != local__buf) 


free(buf); 


return (count > = 0) 2? BDT__WRITE__FINISHED : 


BDT__WRITE__ABORT; 


If you want to retrieve data from the XNS server use 
BulkData1__immediateSink as in the following example: 


Filing6__Retrieve(connected, bulkretrieveproc, remotehandle, 


BulkData1__immediateSink, session); 


In the above example, the bulk data transfer procedure that must 
be supplied is called bulkretrieveproc. It might look as follows: 


int 


bulkretrieveproc (connected) 
COURIERFD connected; 


{ 


int 
int 
int 
int 
int 


chars__to__save = 0; 
charset = 0; 

count; 

do__translate; 


residule__count; 


residule__count = 0; 
DURING { 


do__translate = (filetypevalue = = 
TYPE__VPMailNote || filetypevalue = = 
TYPE__A); 
erro = 0; 
while ((count = cour__bdt__read(connected, 
&file__buf{chars__to__save], sizeof(file__buf) - 
chars__to__save)) > 0) { 
bytessent + = count; 
if (do__ translate) 
count = translate__and__write(fout, 
file __buf, count + chars__to__save, 
&charset, &chars__to__save); 
else 
count = write(fout, file__buf, count); 
if (count < 0) { 
perror("write"); 
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signal(SIGINT, SIG__IGN); 
E_RETURN(BDT__READ__ABORT); 


} 
if (hash) { 
count + = residule__count; 
for (; count > = 1024; count -= 1024) 
putchar(’ #’); 
residule__count = count; 
fflush(stdout); 
} 


} 
if (count < 0) 
perror("netin"); 
else if (charset = = 0 && chars__to__save == 1 
&& file__buf[0] == ‘\r’) £ 
if (write(fout, "\n", 1) < 1) 
perror("write"); 
} 
} HANDLER € 
signal(SIGINT, SIG__IGN); 
FE RETURN(BDT__READ__ABORT),; 
} END__HANDLER; 


signal(SIGINT, SIG__IGN); 
return BDT__READ__FINISHED; 


} 


This example does more than is necessary for bulk data retrieval, 
because it handles various types of Xerox documents. What is 
important here is that this procedures reads a specified file from 
the XNS server and writes it to the UNIX file given by fout. 
cour__bdt__read, provided by the XNS basic software, is the 
lower-level bulk data transfer read function. See the XNS for 
UNIX System V.3 Programming Guide for information on this 
function. More details on bulk data transfer are described in the 
Xerox Filing Protocol manual. 





XNS error handling 
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You must write your own error handling routines to catch errors 
returned by the XNS library functions. The XNS service reference 
manuals for each of the six respective service explains the error. 
Both the Document Interfaces Toolkit Reference Manual and the 
respective XNS service reference manuals show which errors are 
reported. Two errors that do not show up in the XNS service 
reference manuals are courier generated errors, REJECT_ERROR 
and SYSTEM__ERROR. These two errors may be generated when 
calling any XNS function. The example code below will show 
how to catch these errors. 


Using the PrintingService GetPrinterStatus function as an 
example, the code fragment below switches on Exception.Code, 
REJECT__ERROR, and SYSTEM__ERROR to print the appropriate 
error message: 


#include <courier/except.h > 
#include <Printing3__de.h> 


XNS SERVICES 


secondlevelerror, syserror; 


Cardinal probnum; 


secondlevelerror= 0; 
syserror = Q; 
DURING 


StatusResult = 
GetPrinterStatus(getprintstatusconnected, NULL); 


HANDLER { 


char * msg; 

switch (Exception.Code) { 

case ServiceUnavailable: 
msg = "GetStat: Service unavailable"; 
break; 

case SystemError: 
msg = "GetStat: System Error"; 
break; 

case Undefined: 
msg = "GetStat: Undefined error"; 
probnum = CourierErrArgs(UndefinedArgs, problem); 
secondlevelerror = 1; 
break; 


case REJECT__ERROR: 
switch (CourierErrArgs(rejectionDetails, designator)) { 
case 0: 
msg = "GetStat: REJECT: noSuchProgramNumber"; 
break; 
case 1: 
msg = "GetStat: REJECT: noSuchVersionNumber'"; 
break; 
case 2: | 
msg = "GetStat: REJECT: noSuchProcedureValue"; 
break; 
case 3: 
msg = "GetStat: REJECT: invalidArgument"; 
break; 
default: 
msg = "GetStat: REJECT: unknown error"; 
secondlevelerror = 1; 
probnum = CourierErrArgs(rejectionDetails, 
designator); 
break; 
} 
break; 
case SYSTEM__ERROR: 
msg ="GetStat: Connection Error"; 
syserror = 1; 
break; 
default: 
msg = "GetStat: Unknown Error"; 
secondlevelerror = 1; 
probnum = Exception.Code; 
break; 


} 
fprintf (stderr,"\t\t\tError: %s\n", msg); 
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if (syserror) { 
syserror = 0; 
fprintf (stderr,"\t\t\t%s\n", Exception.Message),; 
} 
if (secondlevelerror) { 
secondlevelerror = 0; 
fprintf (stderr, "\t\t\tProblem number: %d\n", probnum); 


} 
} END__HANDLER; 


} 


The DURING, HANDLER, and END__HANDLER macros are 
defined in the except.h header file. When an error occurs, the 
XNS function will return a code number and sometimes a 
problem number. The above example switches on the error 
code in order to print out the corresponding error message as 
defined in the case statements. If the error can also show which 
problem occurred, you can get the problem number by using the 
CourierErrArgs function. CourierErrArgs is a function provided 
by the basic XNS software that returns arguments for errors 
encountered. Refer to the XNS for UNIX System V.3 
Programming Guide manual for more information on this 
function. 





Linking with libraries and including headers 
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The following libraries should be linked when compiling your 
XNS program: 


e = §=6flibxnstk.a 
e § /ibcourier.a 


The /ibxnstk.a library contains the XNS functions provided by the 
Document Interfaces Toolkit. 


The /ibcourier.a library contains lower-level courier definitions. 
This library should be linked with all programs using the XNS 
portion of the Document Interfaces Toolkit. 


An example of a make file that can be used to link your XNS 
programs is listed below: 


#File:MyProgram.mk 


CC = cc-g $(CFLAGS) 
T =MyProgram 


TOOLKITLIB = /usr/include/tk/libxnstk.a 
MISC = /usr/new/lib/libcourier.a 


all: program 
program: $(T) 


$(T): $(T).c 
$(CC) $(T).c $(TOOLKITLIB) $(MISC) -o $(T) 


#end of Makefile 
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Authentication service 


GAP service 


Clearinghouse service 


The following sections list the recommended include files for 
each XNS service. 


# include 
# include 


# include 
# include 
# include 


# include 


# include 


# include 
# include 


# include 
# include 
# include 


# include 


# include 


# include 
# include 


# include 
# include 
# include 


# include 


<stdio.h> 


<sys/types.h> 


<errno.h> 


<signal.h> 


<courier/except.h > 


/* contains standard I/O definitions */ 
/* contains “system” types definitions 


oh 
/* contains integer expression 
definition for errors */ 


/* contains facilities for handling 


exceptional conditions */ 
/* contains macro definitions 
for the exception handler */ 


< courier/Authenti2.h > /* contains Toolkit 


Authentication functions, 
can use Authenti2__de.h 
instead */ 


<courier/FilingSu1.h> /* contains the definition for 


<stdio.h> 
<sys/types.h> 


<errno.h> 


<signal.h> 


< courier/except.h > 


j* 
/* 


/* 


]* 


< courier/Gap3.h > 


the CH__StringToName 
function */ 


contains standard I/O definitions */ 
contains “system” types definitions 
a 
contains integer expression 
definition for errors */ 
contains facilities for handling 
exceptional conditions */ 
/* contains macro definitions 
for the exception handler */ 
/* contains Toolkit Gap 
functions, can use 
Gap3__de.h instead */ 


<courier/gapcontrol.h> /* contains service types for 


<stdio.h> 
<sys/types.h> 


<errno.h > 


<signal.h> 


< courier/except.h > 


/* 
/* 


/* 


/* 


GAP TTY services */ 


contains standard I/O definitions */ 
contains “system” types definitions 
ey 
contains integer expression 
definition for errors */ 
contains facilities for handling 
exceptional conditions */ 
/* contains macro definitions 
for the exception handler */ 


<courier/Clearing2.h > /* contains Toolkit 


Clearinghouse functions, can 
use Clearing2__de.h instead 
| 
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#include <courier/FilingSu1.h> /* 


#include <courier/Authenti2.h> /* 


#include <courier/filetypes.h > 


#include <courier/CHEntrie0.h > /* 


#include <stdio.h> i 
#include <sys/types.h> /* 


#include <errno.h> /* 
#include <signal.h> he 


# include <courier/except.h > 


#include <courier/Inbasket2.h> /* 


#include <courier/MailTran5.h> /* 


#include <courier/FilingSu1.h> /* 


#include <courier/xnstime.h > 


#include <ctype.h> iC 


#include <stdio.h> is 
#include <sys/types.h> /* 


#include <errno.h> a 
#include <signal.h> i 
# include <courier/except.h > 


#include <ctype.h> 
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contains the 
CH__StringToName function 
definition*/ 

contains Toolkit 
Authentication functions, 
can use Authenti2__de.h 
instead */ 

contains definitions for 
various Xerox file types */ 
contains definitions for 
Clearinghouse properties */ 


contains standard I/O definitions */ 
contains “system” types definitions 


contains integer expression 
definition for errors */ 
contains facilities for handling 
exceptional conditions */ 


contains macro definitions 
for the exception handler */ 
contains Toolkit Inbasket 
functions, can use 
Inbasket2__de.h instead */ 
contains Toolkit Mail 
Transport functions, can use 
MailTran5__de.h instead */ 
contains the 
CH__StringToName function 
definition */ 

contains the difference 
between XNS and UNIX 
times */ 


contains functions for testing 
characters */ 


contains standard I/O definitions */ 
contains “system” types definitions 


contains integer expression 
definition for errors */ 
contains facilities for handling 
exceptional conditions */ 

/* contains macro definitions 


for the exception handler */ 


/* contains functions for testing 
characters */ 


#include <sys/times.h> /* contains types and functions for 


manipulating date and time */ 


#include <courier/FilingSu1.h> /* contains 
#include <courier/Authenti2.h> /* contains Toolkit 


Authentication functions, 
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Printing service 


can use Authenti2__de.h 
instead */ 

#include <courier/Filing6.h> = /* contains Toolkit Filing 
functions, can use 
Filing6__de.h instead */ 

#include <courier/filetypes.h> /* contains definitions for 
various Xerox file types */ 

#include <courier/xnstime.h> /* contains the difference 
between XNS and UNIX 
times */ 

#include <dirent.h> /* contains filesystem-independent 

directory information */ 


#include <stdio.h> /* contains standard I/O definitions */ 

#include <sys/types.h> /* contains “system” types definitions 
*/ 

#include <errno.h> /* contains integer expression 
definition for errors */ 

#include <signal.h> /* contains facilities for handling 


exceptional conditions */ 
#include <courier/except.h> /* contains macro definitions 
for the exception handler */ 
#include <courier/Printing3.h> /* contains Toolkit Printing 
functions, can use 
Printing3__de.h instead */ 
#include <pwd.h> /* contains the passwd structure */ 
#include "papersize.h" = /* contains paper dimension 
descriptions */ 





XNS filing service 
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Remote files must be represented in the following form before 
the file can be accessed on the XNS file server: 


/path![version]/filename! [version] 


For example, suppose the remote file you wish to access is called 
“MyFile” and it’s located on the remote directory called 
“RemoteDirect”. If you specify the path as 


/RemoteDirect/MyFile 


you'll get an access error message indicating that the file does 
not exist. Instead, the path must be: 


/RemoteDirect! 1/MyFile!1 


where “RemoteDirect” and “MyFile” both have a version number 
of 1 in this example. 


In order to access a file, a directory handle must first be obtained 
and opened for the entire path. For example, to access the file 
“/directory1/directory2/MyFile”, you must acquire the handle for 
“Idirectory1” and open this directory using the Open() function. 
Next, you must acquire the handle for “/directory1/directory2” 
and open it. With this handle you can now access “MyFile”. 


DOCUMENT INTERFACES TOOLKIT USER GUIDE 


XNS SERVICES 





Available XNS functions 


AbortRetrival() 
AddGroupProperty() 
AdditemProperty() 
AddMember() 

AddSelf() 

BeginPost() 
BeginRetrieval() 
ChangeAttributes() 
ChangeBodyPartsStatus() 
ChangeControls() 
Changeltem() 
ChangeMessageStatus() 
ChangeSimpleKey() 
ChangeStrongKey() 


Close() 


Continue() 


Copy() 
Create() 
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This sections gives an alphabetical listing of all functions calls 
available within the XNS /ibxnstk.a library. The headers associated 
with each XNS function are listed within the square brackets ([ ]) 
following its description. Note that the prefix for each function 
has been left off. You must include the prefix associated with 
each function if you use the [service].h header. 


direct the mail service to retain a message until the client is ready 
to accept [Mai/Tran5.h, MailTran5__de.h] 


add a unique group type property to an object [Clearing2.h, 
Clearing2__de.h] 


add a property of a specified value to an object [Clearing2.h, 
Clearing2__de.h] 


add a new member to a group type property of an object 
[Clearing2.h, Clearing2__de.h] 


add user to the Clearinghouse database [Clearing2.h, 
Clearing2__de.h] 


initiate the posting of a message with a mail service [MailTran5.h, 
MailTran5__de.h] 


initiate the retrieval of one or more messages from a specified 
delivery slot [MailTran5.h, MailTran5__de.h] 


modify the access-related attributes of a specific file [Filing6.h, 
Filing6__de.h] 


update the status of one or more message body parts 
[Inbasket2.h, Inbasket2__de.h] 


modify specific controls associated with a file [Filing6.h, 
Filing6__de.h] 


assign a new value to an item type property [Clearing2.h, 
Clearing2__de.h] 


update a specified range of messages from new to known 
[inbasket2.h, Inbasket2__de.h] 


change a simple key that is registered with the Authentication 
Service [Authenti2.h, Authenti2__de.h] 


change a strong key that is registered with the Authentication 
Service [Authenti2.h, Authenti2__de.h] 


indicate to the File Service that a specific file handle is no longer 
wanted for the remainder of the current session [Filing6.h, 
Filing6__de.h] 


determine the duration, in seconds, permitted for an inactive 
session before it is terminated by the File Service [Filing6.h, 
Filing6__de.h] 


duplicate an existing file or directory [Filing6.h, Filing6__de.h] 
make a new file [Filing6.h, Filing6__de.h] 
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Create() 
CreateAlias() 
CreateObject() 
CreateSimpleKey() 
CreateStrongKey() 


CheckSimpleCredentials() 
Delete() 
Delete() 


DeleteAlias() 
DeleteMember() 
DeleteObject() 
DeleteProperty() 


DeleteSelf() 
DeleteSimpleKey() 


DeleteStrongKey() 
Deserialize() 
EndPost() 
EndRetrieval() 


Find() 
GetAttributes() 


GetControls() 
GetPrinterProperties() 
GetPrintRequestStatus() 


GetPrinterStatus() 
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initiate a terminal emulation session with a mainframe computer 
system [MailTran5.h, MailTran5__de.h] 


add a new alias to an object in the Clearinghouse database 
[Clearing2.h, Clearing2__de.h] 


create a unique object in the Clearinghouse database 
[Clearing2.h, Clearing2__de.h] 


register a new simple key with the Authentication Service 
[Authenti2.h, Authenti2__de.h] 


register a strong key with the Authentication Service [Authenti2.h, 
Authenti2__de.h] 


verify the identity of the initiator [Authenti2.h, Authenti2__de.h] 
remove an existing file [Filing6.h, Filing6__de.h] 


remove one or more contiguous messages from the inbasket 
[Inbasket2.h, Inbasket2__de.h] 


remove an alias of an object in the Clearinghouse database 
[Clearing2.h, Clearing2__de.h] 


delete a member from a group type property of an object 
[Clearing2.h, Clearing2__de.h] 


delete a unique object from the Clearinghouse database 
[Clearing2.h, Clearing2__de.h] 


remove a specific property from an object [C/earing2.h, 
Clearing2__de.h] 


deletes the user [Clearing2.h, Clearing2__de.h] 


delete a simple key that is registered with the Authentication 
Service [Authenti2.h, Authenti2__de.h] 


delete a strong key that is registered with the Authentication 
Service [Authenti2.h, Authenti2__de.h] 


reconstruct a file and its descendants from a previously serialized 
file [Filing6.h, Filing6__de.h] 


signal the mail service that the message is complete and no more 
data is to follow [MailTran5.h, MailTran5__de.h] 


end the current delivery slot retrieval sequence [Mai/Tran5.h, 
MailTran5__de.h] 


locate and open a file in a directory [Filing6.h, Filing6__de.h] 


retrieve the attribute and attribute value pairs of a specific file 
[Filing6.h, Filing6__de.h] 


determine the file access associated with a specific file [Filing6.h, 
Filing6__de.h] 


query the print service for the static properties of a printer 
[Printing3.h, Printing3__de.h] 


ascertain the status of a document that was sent to a printer 
[Printing3.h, Printing3__de.h] 


determine the availability of the print service [Printing3.h, 
Printing3__de.h] 
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GetSize() 
GetStrongCredentials() 
IsMember() 

List() 

ListAliases() 


ListAliasesOf() 
ListDomains() 


ListDomainsServed() 
ListOrganizations() 


ListObjects() 
ListProperties() 


Logon() 
Logon() 


Logoff() 
Logoff() 


Lookup Object() 


MailCheck() 
MailPoll() 


MailPollQ) 
Move() 


Open() 
PostOneBodyPart() 
PrintQ) 


Replace() 
ReplaceBytes() 


Retrieve() 
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retrieve a tally of the disk space occupied by all the messages in 
an inbasket [Inbasket2.h, Inbasket2__de.h] 


acquire privileged user authority from the Authentication Service 
[Authenti2.h, Authenti2__de.h] 


determine if a named object is a member of a group type 
property [Clearing2.h, Clearing2__de.h] 


enumerate the files in a directory and return desired attributes 
[Filing6.h, Filing6__de.h] 


list the objects in a specific domain which are aliases 
[Clearing2.h, Clearing2__de.h] 


list the aliases of an object [Clearing2.h, Clearing2__de.h] 
list domains within an organization [Clearing2.h, Clearing2__de.h] 


obtain a list of the domains served by the Clearinghouse 
[Clearing2.h, Clearing2__de.h] 


list the names of organizations in the Clearinghouse database 
[Clearing2.h, Clearing2__de.h] 


list objects in a domain [Clearing2.h, Clearing2__de.h] 


list the ID number of every property associated with an object 
[Clearing2.h, Clearing2__de.h] 


initiate access to a File Service [Filing6.h, Filing6__de.h] 


initiate a new inbasket session with the mail service [/nbasket2.h, 
Inbasket2__de.h] 


end the current File Service session [Filing6.h, Filing6__de.h] 


end an inbasket session with the mail service [/nbasket2.h, 
Inbasket2__de.h] 


ascertain the complete name of an object in the Clearinghouse 
database [Clearing2.h, Clearing2__de.h] 


determine the state of an inbasket [/nbasket2.h, Inbasket2__de.h] 


quickly determine the state of an inbasket [/nbasket2.h, 
Inbasket2__de.h] 


determine if messages are present in a delivery mail slot 
[MailTran5.h, MailTran5__de.h] 


change the directory structure of the filing service without 
creating or deleting files [Filing6.h, Filing6__de.h] 


make a file available for use [Filing6.h, Filing6__de.h] 
submit data to a mail service [MailTran5.h, MailTran5__de.h] 


access bulk transfer data in a source and send it to the print 
service queue [Printing3.h, Printing3__de.h] 


remove the contents of a file, and then replace it with data 
received from a specific source [Hiling6.h, Filing6__de.h] 


overwrite the contents of a file or to append new data to a 
file[Filing6.h, Filing6__de.h] 


read the contents of an existing file and transfer them to the 
client [Filing6.h, Filing6__de.h] 
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RetrieveAddresses() 
RetrieveBodyParts() 


RetrieveBytes() 


RetrieveContent() 
RetrieveEnvelope() 
RetrieveEnvelopes() 
Retrieveltem() 
RetrieveMembers() 


Serialize() 


ServerPoll() 


Store() 
UnifyAccessLists() 


query the clearinghouse server for a list of all the network 
addresses it recognizes [Clearing2.h, Clearing2__de.h] 


copy specific parts of an inbasket message [/nbasket2.h, 
Inbasket2__de.h] 


read a range of bytes within a file [Filing6.h, Filing6__de.h] 


extract the message in the envelope that is at the head of the 
delivery slot queue [MailTran5.h, MailTran5__de.h] 


extract an envelope’s header information from the delivery slot 
queue [MailTran5.h, MailTran5__de.h] 


extract a particular message (envelope) from the inbasket 
[(Inbasket2.h, Inbasket2__de.h] 


determine the value of an item type property that is associated 
with an object [Clearing2.h, Clearing2__de.h] 


extract, or retrieve, the value of a group type property associated 
with an object (Clearing2.h, Clearing2__de.h] 


compress all the descriptive information and data of a file and its 
descendants into a series of eight-bit bytes [Filing6.h, 
Filing6__de.h] 


determine if the mail service currently in use will accept 
additional messages for posting [Mailtran5.h, Mailtran5__de.h] 


create a file that contains specific data [Filing6.h, Filing6__de.h] 


assign the access list attributes (i.e., permissions) of a directory 
to all its descendants [Filing6.h, Filing6__de.h] 





Duplicate functions 
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There are some duplicate function names in the Document 
Interfaces Toolkit libraries, as outlined in Table 6-1. 
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Table 6-1. Duplicate XNS functions 


_ 


Delete() Filing6.h Remove an existing file 
Inbasket2.h Remove messages from Mail 


Logoff() Filing6.h End current File Service 
End inbasket Mail session 


Mailpoll() Inbasket2.h Determine state of inbasket 
MailTran5.h Determine if messages are in 
delivery mail slot 


Logon() Filing6.h Initiate access to File Service 
Inbasket2.h Initiate inbasket Mail session 





If you must combine some duplicate functions into one program, 
use the appropriate header file and prefix your functions to 
specify their full name. See the Using the libxnstk.a library 
section at the beginning of this chapter, or the Document 
Interfaces Toolkit Reference Manual for more details on using 
appropriate header files. 
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7. XNS function examples 


This chapter presents example code fragments for the XNS 
functions to illustrate their usage. Only the major functions have 
been listed. Consult the Document Interfaces Toolkit Reference 
Manual for a complete description of all the available XNS 
functions. 


The examples are organized alphabetically according to their 
header file name. Each example has the following format: 


Function name 

Function brief description 
Function syntax 

Example code fragment 
Description of the example 





Authenti2.h 


Authentication2__CheckSimpleCredentials() 


DOCUMENT INTERFACES TOOLKIT USER GUIDE 


The Authentication2__CheckSimpleCredentials() function is 
used to verify that the correct password has been submitted to 
the Authentication Service. 


Authentication2__CheckSimpleCredentials(__Connection, 
__BDTprocptr, credentials, verifier) 


Example 


Authentication2 CheckSimpleCredentialsResults 
checksimplecredresult; 


Authentication2 Credentialscredentials; 
Authentication2 Verifier — verifier; 


char *checksecnameptr; 


checksecnameptr = MakeSimpleCredsAndVerifier( 
secnameptr, 0, &credentials, &verifier); 


checksimplecredresult = 
Authentication2 CheckSimpleCredentials(connected, 
NULL, credentials, verifier); 


In the preceding example, MakeSimpleCredsAndVerifier 
creates the simple credentials and verifier for the user. 
Authentication2__CheckSimpleCredentials compares the 
simple key in verifier against the simple key that is registered for 
the user. credentials contains information regarding the user’s 
name and password. checksimplecredresult has a value of TRUE 
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if the simple key registered for the user and the simple key in 
verifier match. connected contains the courier connection 
number. A method for obtaining this connection number is 
shown in Chapter 6. Bulk data transfer is not required, so 
__BDTprocptr is set to NULL. 


Authentication2__DeleteSimpleKey() 


Authentication2__ 


The Authentication2__DeleteSimpleKey() function is used to 
delete a strong key that is registered with the Authentication 
Service. 


Authentication2__DeleteSimpleKey(__Connection, 
__BDTprocptr, credentials, verifier, name) 


Example 
Authentication2 Credentials credentials; 
Authentication2 Verifier verifier; 
char *deletenameptr; 


deletenameptr = 
MakeSimpleCredsAndVerifier(nameptr, 0, &credentials, 
&verifier); 


(void)Authentication2 DeleteSimpleKey 
(connected, NULL, credentials, verifier, 
*CH_ StringToName(nameptr)); 


In the preceding example, the strong key registered with 
nameptr will be deleted from the Authentication Service. 
MakeSimpleCredsAndVerifier creates the strong credentials and 
verifier for the user. nameptr contains the name of the user 
whose strong key will be deleted. CH__StringToName() 
translates this name into a three-part name so that it can be 
recognized by the Clearinghouse. connected contains the 
courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. Bulk data transfer is 
not required, so _BDTprocptr is set to NULL. 


GetStrongCredentials() 


The Authentication2__GetStrongCredentials() function is used 
to retrieve credentials in order to prove one’s strong identity to a 
specified communications recipient. 


Authentication2__GetStrongCredentials(__Connection, 
__BDTprocptr, initiator, recipient, nonce) 


Example 


Authentication2 GetStrongCredentialsResults 
strongcredresult; 
char authserver[128]; 


strcpy(authserver, "Authentication 
Service:CHServers: CHServers'); 


strongcredresult = 
Authentication2 GetStrongCredentials(connected, 
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NULL, *CH_ StringToName(nameptr), 
*CH_ StringToName(authserver), nonce); 


In the preceding example, strong credentials are created for the 
user defined by nameptr in order to prove the user’s identity to 
the recipient, authserver. The well-known name of the 
Authentication Service is “Authentication 
Service:CHServers:CHServers” which is copied into authserver. 
CH__StringToName() translates both nameptr and authserver 
into three-part names so that they may be recognized by the 
Clearinghouse. strongcredresult has one member, 
credentialsPackage which is encrypted with the user’s key. 
Once decrypted, it will contain the user’s credentials. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. 
Bulk data transfer is not required, so __BDTprocpttr is set to 
NULL. 





Clearing2.h 


Clearinghouse2_ AddItemProperty() 
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The Clearinghouse2__AddItemProperty() function is used to 
add a property of a specified value to an object. 


Clearinghouse2_ AdditemProperty(__Connection, 
__BDTprocptr, name, newProperty, value, agent) 


Example 
Clearinghouse2__AddlitemPropertyResults additemprtyrsit; 
char *nametoaddpropertyto; 


Clearinghouse2 Item value; 
char *val[3]; 


nametoaddpropertyto = “Jones:Sunnyvale: USA"; 
val[0] = "ABCD Division"; 


value.length = 1; 
value.sequence = (Unspecified *)&val(0]; 


additemprtyrsit = Clearinghouse2 AdditemProperty( 
connected, NULL, — 
*CH StringToName(nametoaddpropertyto), 
CHEntriesO _user, value, *agent); 


In the preceding example, the user property is added to 
“Jones:Sunnyvale: USA” in the Clearinghouse database. Properties 
for Clearinghouse databases include an ID number and a value, 
or descriptive field. In this example, CHEntriesO__user returns 
an ID of 10003 as defined in the CHEntries0.h header file, 
indicating to the Clearinghouse that a user property is to be 
added. The Clearinghouse property value is defined by the 
value argument, or “ABCD Division”. CH__StringToName() is 
used to translate nametoaddpropertyto into a three-part name 
so that it will be recognized by the Clearinghouse. agent 
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Clearinghouse2__AddMember() 


Clearinghouse2_ AddSelf() 


contains the client’s credentials and verifier, as defined by the 
Authentication protocol. The returned argument additemprtyrslt 
contains the full name of “Jones:Sunnyvale:USA”. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so ___BDTprocptr is set to NULL. 


The Clearinghouse2__AddMember() function is used to add a 
new member to a group type property of an object. 


Clearinghouse2_ AddMember(__Connection, 
__BDTprocptr, name, property, newMember, agent) 


Example 
Clearinghouse2 _AddMemberResults addmemberresult; 
char *grouptoaddto; 
char *newmember; 


grouptoaddto = ‘xnstoolkit:green1:fermat”; 
newmember = ‘“Jones:Sunnyvale:USA"; 


addmemberresult = Clearinghouse2 AddMember( 
connected, NULL, *CH StringToName(grouptoaddto), 
CHEntriesO members, _ 
*CH StringlroName(newmember), *agent); 


In the preceding example, a new member, 

“Jones:Sunnyvale:USA” is added to the “xnstoolkit:green1:fermat” 
group within the Clearinghouse database. CH__StringToName() 
translates both “Jones:Sunnyvale:USA” and 
“xnstoolkit:green1:fermat” to three-part names so that they may 
be recognized by the Clearinghouse. CHEntriesO__members 
indicates to the Clearinghouse that a member group property is 
being added. No Bulk Data Transfer is required, so _ BDTprocptr 
is set to NULL. The returned parameter addmemberresult has 
one member, distinguishedObject, which contains the 
distinguished name of “xnstoolkit:green1:fermat”. connected 
contains the courier connect number. A method for obtaining 
this connection number is shown in Chapter 6. 


The Clearinghouse2_ AddSelf() function is used to add the user 
identified by the agent argument to a group property of an 
object. 


Clearinghouse2_ AddSelf(__Connection, _ BDTprocptr, 
name, property, agent) 


Example 
Clearinghouse2 AddSelfResults addselfresult; 
char *grouptoaddto; 


grouptoaddto = "“xnstoolkit:green1:fermat’ ; 


addselfresult = Clearinghouse2__AddSelf(connected, 
NULL, *CH_ StringToName(grouptoaddto), 
CHEntriesO _members, *agent); 
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Clearinghouse2__Changeltem() 
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In the preceding example, the user is added to the group 
property in the Clearinghouse database. CHEntriesO__members 
indicates to the Clearinghouse that a Clearinghouse name, or 
member, is being added to a group property. agent identifies 
the user and verifies the user’s credentials. The user is then 
added to the group property of grouptoaddto, or 
“xnstoolkit:green1:fermat”. CH__StringToName() translates 
grouptoaddto to a three-part name so that it will be recognized 
by the Clearinghouse. addselfresult will contain the 
distinguished name of “xnstoolkit:green1:fermat”. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so ___BDTprocptr is set to NULL. 


The Clearinghouse2__Changeltem() function is used to assign a 
new value to an item type property. 


Clearinghouse2__Changeltem(__Connection, 
__BDTprocptr,name, property, newValue, agent) 


Example 


Clearinghouse2 ChangeltemResults changeitemresult; 
Clearinghouse2 Item newValue; 

char *newVal(3]; 

char *objectwhoseitemwillbechanged; 


objectwhoseitemwillbechanged = 
“Jones:Sunnyvale: USA"; 


newVal[0] = "XYZ Division"; 


newValue.length = 1; 
newValue.sequence = (Unspecified *)&newVal[0]; 


changeitemresult = Clearinghouse2 Changeltem( 
connected, NULL, | 
*CH StringToName(objectwhoseitemwillbechanged), 
CHEntriesO user, newValue, *agent); 


In the preceding example, the value for the user property will be 
changed for “Jones:Sunnyvale:USA” in the Clearinghouse 
database. Properties in the Clearinghouse are defined by a ID 
number followed by a value field. CHEntriesO__user returns 
10003 as defined by the CHEntries0.h header file. 10003 is the 
code for user property ID, indicating to the Clearinghouse that a 
user property is to be changed. The new value for the user 
property is defined by the newValue argument in this example, 
or “XYZ Division”. CH__StringToName() translates 
objectwhoseitemwillbechanged into a three-part name so that 
it can be recognized by the Clearinghouse. The returned 
argument changeitemresult contains the full path name of 
“Jones:Sunnyvale:USA”. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. No bulk data transfer is required, 
so _BDTprocptr is set to NULL. 
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Clearinghouse2__CreateAlias() 
The Clearinghouse2__CreateAlias(). function is used to add a 
new alias to an object in the Clearinghouse database. 


Clearinghouse2__CreateAlias(__Connection, 
__BDTprocptr, alias, sameAs, agent) 


Example 
Clearinghouse2 CreateAliasResults createaliasresult; 
char *alias; 
char *nametoalias; 


nametoalias = “Johnson:Sunnyvale: USA"; 
alias = "JJ:San Jose:USA"; 


createaliasresult = Clearinghouse2_CreateAlias( 
connected, NULL, *CH_ StringToName(alias), 
*CH _StringToName(nametoalias), *agent); 


In the preceding example, an alias is created for 
“Johnson:Sunnyvale:USA”. The alias will be “JJ:San Jose:USA”. 
CH_ StringToName() translates alias and nametoalias into 
three-part names, so that they can be recognized by the 
Clearinghouse. agent contains the credentials and verifier of the 
client as defined in the Authentication protocol. No Bulk Data 
Transfer is required, so __BDTprocptr is set to NULL. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. 


Clearinghouse2__CreateObject() 


The Clearinghouse2__CreateObject() function is used to create 
a new distinguished object in the Clearinghouse database. 


Clearinghouse2__CreateObject(__Connection, 
__BDTprocptr, name, agent) 


Example 


char * object; 
object = “Jones:Sunnyvale: USA"; 


(void)Clearinghouse2_ CreateObject(connected, NULL, 
*CH_StringToName(object), *agent); 


In the preceding example, the object “Jones:Sunnyvale:USA” is 
created in the Clearinghouse database. CH__StringToName() 
translates object into a three-part name so that it can be 
recognized by the Clearinghouse. agent contains the client’s 
credentials and verifier as defined in the Authentication protocol. 
No Bulk Data Transfer is required, so __ BDTprocptr is set to 
NULL. connected contains the courier connection number. A 
method for obtaining this connection number is shown in 
Chapter 6. 
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Clearinghouse2__DeleteMember() 
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The DeleteAlias() function is used to remove an alias of an 
object in the Clearinghouse database. 


DeleteAlias(__ Connection, _BDTprocptr, alias, agent) 


Example 
Clearinghouse2_DeleteAliasResults deletealiasresult; 
char *aliastodelete; 


aliastodelete = "JJ:San Jose:USA"; 


deletealiasresult = Clearinghouse2 DeleteAlias( 
connected, NULL, *CH_ StringToName(aliastodelete), 
*agent); 


In the preceding example, the alias “JJ:San Jose:USA” is deleted 
from the Clearinghouse database. CH__StringToName() 
translates aliastodelete into a three-part name so that it can be 
recognized by the Clearinghouse. agent contains credentials and 
verifier of the client as defined in the Authentication protocol. 
The returned argument deletealiasresult contains the full name 
of the object to which “JJ:San Jose:USA” was aliased. No Bulk 
Data Transfer is required, so ___BDTprocptr is set to NULL. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. 


The Clearinghouse2__DeleteMember() function is used to 
delete a member from a group type property of an object. 


Clearinghouse2__DeleteMember(__Connection, 
__BDTprocptr, name, property, member, agent) 


Example 
Cleari nghouse2_DeleteMem berResults deletememrslt; 
char *grouptodeletefrom; 
char *membertodelete; 


grouptodeletefrom = "xnstoolkit:green1:fermat’ ; 
membertodelete = "GBeichler:San Jose: USA"; 


deletememrsit = Clearinghouse2 DeleteWMember( 
connected, NULL, i 
*CH StringToName(grouptodeletefrom), 
CHEntriesO members, 
*CH_StringToName(membertodelete), *agent); 


} 


In the preceding example, “GBeichler:San Jose:USA” is deleted 
from the group property of xnstoolkit:green1:fermat. 
CHEntriesO__members returns the value of 3 as defined by the 
CH Entries0.h header file. The number 3 is the code for member, 
indicating to the Clearinghouse that a member is to be changed 
or deleted. CH__StringToName() translates grouptodeletefrom 
into a three-part name so that it can be recognized by the 
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Clearinghouse2__DeleteObject() 


Clearinghouse2__DeleteProperty() 


Clearinghouse. The agent argument contains the client’s 
credentials and verifier, as defined in the Authentication protocol. 
The returned argument deletememrslt contains the full path 
name of “xnstoolkit:green1:fermat”. No bulk data transfer is 
required, so __ BDTprocptr is set to NULL. connected contains 
the courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. 


The Clearinghouse2__DeleteObject() function is used to delete 
an object from the Clearinghouse database. 


Clearinghouse2__DeleteObject(__Connection, 
__BDTprocptr, name, agent) 


Example 


char * objecttodelete; 
objecttodelete = "“Jones:Sunnyvale: USA"; 


(void)Clearinghouse2_DeleteObject(connected, NULL, 
*CH_ StringToName(objecttodelete), *agent); 


In the preceding example, “Jones:Sunnyvale:USA” is deleted from 
the Clearinghouse database. All aliases that point to 
“Jones:Sunnyvale:USA” are also deleted. CH__StringToName() 
translates objecttodelete into a three-part name so that it can be 
recognized by the Clearinghouse. agent contains the client’s 
credentials and verifier, as defined in the Authentication protocol. 
Bulk data transfer is not required, so _ BDTprocptr is set to 
NULL. connected contains the courier connection number. A 
method for obtaining this connection number is shown in 
Chapter 6. 


The Clearinghouse2__DeleteProperty() function is used to 
remove a specific property from an object. 


Clearinghouse2__DeleteProperty(__Connection, 
__BDTprocptr, name, property, agent) 


Example 


Clearinghouse2__DeletePropertyResults deleteproprtyrsit; 
char *objectwhosepropertywillbedeleted; 


objectwhosepropertywillbedeleted = 
"Jones:Sunnyvale: USA"; 

deleteproprtyrsit = Clearinghouse2 DeleteProperty( 
connected, NULL, _ 
*CH StringToName(objectwhosepropertywillbedeleted), 
CHEntriesO user, *agent); 


In the preceding example, the user property will be deleted from 
“Jones:Sunnyvale:USA” in the Clearinghouse database. 
CHEntriesO__user returns a value of 10003 as defined by the 
CHEntries0O.h header file which indicates to the Clearinghouse 
database that a user property is to be modified. 
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CH__StringToName() translates 
objectwhosepropertywillbedeleted into a three-part name so 
that it can be recognized by the Clearinghouse. agent contains 
the client’s credentials and verifier, as defined by the 
Authentication protocol. The returned argument 
deleteproprtyrsit contains the full path name of 
“Jones:Sunnyvale:USA”. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. Since bulk data transfer is not 
required, _ BDTprocptr is set to NULL. 


Clearinghouse2__DeleteSelf() 


The Clearinghouse2_ DeleteSelf() function deletes the user 
identified by the agent argument from a group type property of 
an object. 


Clearinghouse2_ DeleteSelf(__Connection, _ BDTprocptr, 
name, property, agent) 


Example 


Clearinghouse2 DeleteSelfResults deleteselfresult; 
char *grouptodeletefrom; 


grouptodeletefrom = "xnstoolkit:green1:fermat"; 


deleteselfresult = Clearinghouse2 DeleteSelf( 
connected, NULL, _ 
*CH StringToName(grouptodeletefrom), 
CHEntriesO. members, *agent); 


In the preceding example, the user, as defined by agent, is 
deleted from the group property in the Clearinghouse database. 
agent contains the client’s credentials and verifier, as defined by 
the Authentication protocol. The user will be deleted from the 
“xnstoolkit:green1:fermat” group property. 
CHEntriesO__members returns a value of 3 as defined by the 
CHEntries0.h header file. The number 3 is the code for member, 
indicating to the Clearinghouse that a group property is to be 
modified. deleteselfresult contains the full path name of 
“xnstoolkit:green1:fermat” from which the user was removed. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. 
Since bulk data transfer is not required, _ BDTprocpttr is set to 
NULL. 


Clearinghouse2__IsMember() 


The Clearinghouse2__IsMember() function determines if a 
named object is a member of a group type property. 


Clearinghouse2__IsMember(__Connection, _ BDTprocptr, 
memberOf, property, secondaryProperty, name, 
agent) 


Example 


Clearinghouse2__IsMemberResults ismemberresult; 
char *objectwithgroupproperty; 
char *lookingforthisname; 
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objectwithgroupproperty = “xnstoolkit:green1:fermat"; 
lookingforthisname = “Jones:Sunnyvale: USA"; 


ismemberresult = Clearinghouse2 IsMember( 
connected, NULL, _ 
*CH StringToName(objectwithgroupproperty), 
Clearinghouse2 all, Clearinghouse2 _ all, 
*CH_ StringToName(lookingforthisname), *agent); 


In the preceding example, “xnstoolkit:green1:fermat” is queried 
to see if it contains the member “Jones:Sunnyvale:USA”. 
CH_StringToName() translates “xnstoolkit:green1:fermat” and 
“Jones:Sunnyvale:USA” to three-part names, so that they may be 
recognized by the Clearinghouse. Both property and 
secondaryProperty contain the value Clearinghouse2__all, 
indicating that every object belonging to 
“xnstoolkit:green1:fermat” will be compared against 
“Jones:Sunnyvale:USA” to see if a match exists. The returned 
parameter ismemberresult contains two members, isMember 
and distinguishedObject. IsMember is a Boolean variable 
whose value indicates if “Jones:Sunnyvale:USA” was found. 
distinguishedObject contains the full path name of 
“xnstoolkit:green1:fermat”. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. Since bulk data transfer is not 
required, _ BDTprocptr is set to NULL. 


Clearinghouse2__ListAliasesOf() 


The Clearinghouse2__ListAliasesOf() function is used to list the 
aliases of an object. 


Clearinghouse2__ListAliasesOf(__Connection, 
__BDTprocptr, pattern, list, agent) 


Example 
Clearinghouse2 _ListAliasesOfResultslistaliasesofresult; 
char * local; 
char *aliasesoftolist; 


aliasesoftolist = "Jones:Sunnyvale:USA"; 


local = "aliases.Ist"; 
if ((fout = open(local,O CREAT|O TRUNC| 
O WRONLY, 0664)) < 0) { _ 
~——-printf(""\t\tCAN'T OPEN local file\n"); 
return; 


} 


listaliasesofresult = Clearinghouse2 ListAliasesOf( 
connected, bulkretrieveproc, 
*CH StringToName(aliasesoftolist), 
BulkDatal__immediateSink, *agent); 


In the preceding example, all aliases for “Jones:Sunnyvale:USA” 
are retrieved. CH__StringToName() translates 
“Jones:Sunnyvale:USA” into a three-part name so that it may be 
recognized by the Clearinghouse. agent is a structure whose 
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two members contain the credentials and verifier of the client. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. Bulk 
data transfer is required in this example. bulkretrieveproc is the 
C procedure defined by the C programmer that will perform the 
bulk data transfer. An example of such a procedure is shown in 
Chapter 6. In the preceding example, the aliases found for 
“Jones:Sunnyvale:USA” will be placed into the file aliases.Ist. 

The transfer of data into aliases.Ist is actually done within the 
bulkretrieveproc procedure. The opening of the file is illustrated 
here. BulkData1__immediateSink indicates that the data will be 
sinked into the UNIX environment. 


The Clearinghouse2__ListDomain() function is used to list 
domain names within an organization. 


Clearinghouse2__ListDomain(__Connection, 
__BDTprocptr, pattern, list, agent) 


Example 


Clearinghouse2__ TwoPartName pattern; 
Clearinghouse2__ObjectName*nameresult; 
char * local; 


nameresult = CH StringToName(nameptr); 
pattern.organization = nameresult->organization; 
pattern.domain = ‘xns*"; 


local = “domains.|st"; 
if ((fout = open(local,O CREAT|O TRUNC| 
O WRONLY, 0664)) < 0) £ _ 
~— printf("\t\tCAN'T OPEN local file\n"); 
return; 


} 


(void)Clearinghouse2__ListDomain(connected, 
bulkretrieveproc, pattern, BulkDatal _immediateSink, 
*agent); 


The preceding example will list all domains that start with “xns” 
in the organization defined by pattern.organization. fout is a 
pointer to the UNIX file that will contain the list of domains that 
match the pattern. Bulk data transfer is required in this example. 
bulkretrieveproc is the C procedure defined by the C 
programmer that will perform the bulk data transfer. An example 
of such a procedure is shown in Chapter 6. The transfer of data 
into the fout file is done within the bulkretrieveproc procedure. 
The opening of this file is illustrated here. Since data is to be 
sinked into the UNIX environment, BulkData1__immediateSink 
is used. agent contains two members: the client’s credentials 
and the client’s verifier. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. 
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Clearinghouse2__ListDomainServed() 


The Clearinghouse2_ ListDomainServed() function is used to 
obtain a list of the domains served by a specific Clearinghouse 
service. 


Clearinghouse2__ListDomainServed(__Connection, 
__BDTprocptr, domains, agent) 


Example 
char * local: 
local = “domains.|st"; 


if ((fout = open(local,O CREAT|O TRUNC| 
O WRONLY,0664))<0){ | 
~~ printf("\t\tCAN'T OPEN local file\n"); 
return; 


} 


(void)Clearinghouse2__ListDomainServed( connected, 
bulkretrieveproc, BulkDatal i mmediateSink, *agent); 


The preceding example lists all domains served by a specific 
Clearinghouse service and places that list into the UNIX file 
domains.|Ist. Bulk data transfer is required in this example. 
bulkretrieveproc is the C procedure defined by the C 
programmer that will perform the bulk data transfer. An example 
of such a procedure is shown in Chapter 6. The transfer of data 
into the file domains.Ist is done within the bulkretrieveproc 
procedure. The opening of this file is illustrated here. Since data 
is to be sinked into the UNIX environment, 
BulkData1__immediateSink is used. agent contains two 
members, the client’s credentials and verifier. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. 


Clearinghouse2__ListObjects() 
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The Clearinghouse2_ ListObjects() function is used to list the 
objects in a domain that have a specific property associated with 
them. 


Clearinghouse2__ListObjects(__Connection, _ BDTprocptr, 
pattern, property, list, agent) 


Example 
char * local; 
char * pattern; 
local = “objects.|st"; 


if ((fout = open(local,O CREAT|O TRUNC| 
O WRONLY, 0664)) < 0) { _ 
~ printf("\t\tCAN'T OPEN local file\n"); 
return; 


} 


pattern = "gary*:Sunnyvale:USA"; 
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(void)Clearinghouse2 _ListObjects(connected, 
bulkretrieveproc, *CH_ StringToName(pattern), 
Clearinghouse2 all, BulkDatal__immediateSink, *agent); 


In the preceding example, all objects starting with “gary” are 
listed in the domain USA. The results are placed into the UNIX 
file objects.Ist. The argument Clearinghouse2_ all indicates 
that all objects in the domain that match the pattern are to be 
listed. Bulk data transfer is required in this example. 
bulkretrieveproc is the C procedure defined by the C 
programmer that will perform the bulk data transfer. An example 
of such a procedure is shown in Chapter 6. The transfer of data 
into the file “objects.Ist” is done within the bulkretrieveproc 
procedure. The opening of this file is illustrated here. Since data 
is to be sinked into the UNIX environment, 
BulkData1__tmmediateSink is used. agent contains two 
members, the client’s credentials and verifier. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. 
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The Clearinghouse2__ListOrganizations() function is used to list 
the names of organizations in the Clearinghouse database. 


Clearinghouse2__ListOrganizations(__Connection, 
__BDTprocptr, pattern, list, agent) 


Example 
char *nattern; 
char * local; 
local = “organization.I|st"; 


if ((fout = open(local,O CREAT|O TRUNC 
IO WRONLY,0664))<0){ ~~ 
~ printf("\t\tCAN'T OPEN local file\n"); 
return: 


} 
pattern = "*tool*"; 


(void)Clearinghouse2__ListOrganizations(connected, 
bulkretrieveproc, pattern, BulkData1 _immediateSink, 
*agent); 


The preceding example lists all organizations within the 
Clearinghouse database that contain the string “tool”. The 
results are placed into a UNIX file “organization.Ist”. This 
example requires bulk data transfer. bulkretrieveproc is the C 
procedure defined by the C programmer that performs the bulk 
data transfer. An example of such a procedure is shown in 
Chapter 6. The transfer of data into the file “organization.Ist” is 
done within the bulkretrieveproc procedure. The opening of 
this file is illustrated here. Since data is to be sinked into the 
UNIX environment, BulkData1__immediateSink is used. agent 
contains two members, the client’s credentials and verifier. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. 
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Clearinghouse2__ListProperties() 


Clearinghouse2__LookupObject() 
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The Clearinghouse2__ListProperties() function is used to list 
the ID number of every property associated with an object. 


Clearinghouse2__ListProperties(__Connection, 
__BDTprocptr, pattern, agent) 


Example 


Clearinghouse2__ListPropertiesResultsistpropertiesresult; 
char *objectwithproperties; 


objectwithproperties = “xnstoolkit:green1:fermat"; 


listpropertiesresult = Clearinghouse2__ListProperties( 
connected, NULL, 
*CH_ StringToName(objectwithproperties), *agent); 


The preceding example lists the ID number of every property 
associated with “xnstoolkit:green1:fermat”. 

CH__StringToName() translates “xnstoolkit:green1:fermat” into a 
three-part name so that it may be recognized by the 
Clearinghouse. agent contains two members, the client’s 
credentials and verifier. No bulk data transfer is required in this 
example, so ___BDTprocptr is set to NULL. connected contains 
the courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. 


The Clearinghouse2__LookupObject() function is used to query 
the Clearinghouse database for the full name of an object that is 
contained within it. 


Clearinghouse2__LookupObject(__Connection, 
__BDTprocptr, name, agent) 


Example 


Clearinghouse2_LookupObjectResults lookupobjectrsit; 
char *objecttolookup; 


objecttolookup = "Jones:Sunnyvale:USA"; 


lookupobjectrsit = Clearinghouse2 LookupObject( 
connected, NULL, 
*CH_StringToName(objecttolookup), *agent); 


The preceding example queries the Clearinghouse database for 
the full name of “Jones:Sunnyvale:USA”. The results are placed 
into the distinguishedObject member of lookupobjectrslt. 
agent contains two members, the client’s credentials and verifier. 
No bulk data transfer is required in this example, so 
__BDTprocptr is set to NULL. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. 
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Clearinghouse2__RetrieveAddresses() 


Clearinghouse2_ Retrieveltem() 
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The Clearinghouse2__RetrieveAddresses() function is used to 
query the clearinghouse server for a list of all of its network 
addresses. 


Clearinghouse2_ RetrieveAddresses (__Connection, 
__BDTprocptr) 


Example 


Clearinghouse2_RetrieveAddressesResults rtrvaddrrslt; 


rtrvaddrrsit = Clearinghouse2__RetrieveAddresses( 
connected, NULL); 


In the preceding example, rtrvaddrrslt contains a list of the 
network addresses recognized by the Clearinghouse server. The 
Clearinghouse server accessed is based upon the value of 
connected. connected contains the courier connection number. 
No bulk data transfer is required so _ BDTprocptr is set to NULL. 


The Clearinghouse2_ Retrieveltem() function is used to 
determine the value of an item type property that is associated 
with an object. 


Clearinghouse2__Retrieveltem(__Connection, 
__BDTprocptr, pattern, property, agent) 


Example 


Clearinghouse2__RetrieveltemResults retrieveitemresult; 
char *objectwithproperties; 


objectwithproperties = "xnstoolkit:green1:fermat"; 


retrieveitemresult = Clearinghouse2 Retrieveltem( 
connected, NULL, _ 
*CH StringToName(objectwithproperties), 
Clearinghouse2_all, *agent); 


} 


The preceding example returns all item properties of the first 
object encountered that matches “xnstoolkit:green1:fermat” in 
the Clearinghouse database. CH__StringToName() translates 
objectwithproperties into a three-part name so that it may be 
recognized by the Clearinghouse. Clearinghouse2__all indicates 
that all item properties are to be returned. agent contains the 
client’s credentials and verifier. retrieveitemresult contains two 
members: distinguishedObject and value. 
distinguishedObject contains the full name of 
“xnstoolkit:green1:fermat”. value contains the value of the item 
property. No bulk data transfer is required in this example, so 
__BDTprocptr is set to NULL. connected contains the courier 
connection number. A method for obtaining this connection 
number is shown in Chapter 6. 
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Clearinghouse2__RetrieveMembers() 


The Clearinghouse2__RetrieveMembers() function is used to 
retrieve the value of a group type property associated with an 
object. 


Clearinghouse2__RetrieveMembers(_ Connection, 
__BDTprocptr, pattern, property, membership, agent) 


Example 


Clearinghouse2 RetrieveMembersResults retmemrsit; 
Clearinghouse2 Property membersproperty = 3; 
char *grouptoretrievefrom; 

char * local; 


grouptoretrievefrom = "xnstoolkit:green1:fermat"; 


local = "“propvalues.|st"; 
if ((fout = open(local,O CREAT|O TRUNC| 
O WRONLY, 0664)) < 0) { _ 
~— printf("\t\tCAN'T OPEN local file\n"); 
return; 


} 


retmemrsit = Clearinghouse2 RetrieveMembers( 
connected, bulkretrieveproc, 
*CH StringToName(grouptoretrievefrom), 
membersproperty, BulkData1__immediateSink, *agent); 


The preceding example returns the value of the group member 
property associated with “xnstoolkit:green1:fermat. 
CH__StringToName() translates xnstoolkit:green1:fermat into a 
three-part name so that it may be recognized by the 
Clearinghouse. membersproperty has a value of 3 indicating that 
the member group value is to be retrieved. The value of 3 is 
defined by the CHEntries0.h header file to be the member 
property. agent contains the client’s credentials and verifier. 
Bulk data transfer is required in this example. bulkretrieveproc 
is the C procedure defined by the C programmer that will 
perform the bulk data transfer. An example of such a procedure 
is shown in Chapter 6. In the preceding example, the member 
properties found for “Jones:Sunnyvale:USA” will be placed into 
the file “propvalues.Ist”. The transfer of data into propvalues.|st 
is done within the bulkretrieveproc procedure. The opening of 
the file is illustrated here. BulkData1__immediateSink indicates 
that the data will be sinked into the UNIX environment. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. 
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Filing6__Logon() 
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The Filing6__Logon function is used to initiate access to a File 
Service. 


Filing6__Logon(__Connection, _ BDTprocptr, service, 
credentials, verifier) 


Example 


Filing6 Credentials credentials 

Filing6 LogonResultslogonresult; 

Filing6 SecondaryCredentials | secondarycreds; 
char *hostnameptr; 

int name; 

int pwd; 


hostnameptr = “Jones:Sunnyvale:USA" 


name = 0; 

pwd = 0; 

name = MakeSimpleCredsAndVerifier (name, pwd, 
&credentials.primary, &verifier); 


secondarycreds.designator = Filing6 strengthNone; 
credentials.secondary = secondarycreds; 


logonresult = Filing6 Logon(connected, NULL, 
*CH__StringToName(hostnameptr), credentials, verifier); 


session = logonresult.session; 


In the preceding example, a File Service session is initiated for 
“Jones:Sunnyvale:USA”. Setting both name and pwd to 0 cause 
MakeSimpleCredsAndVerifier to find the logged on user and 
the logged on user’s password. The credentials and verifier 
returned from MakeSimpleCredsAndVerifier are then passed to 
the Filing6__Logon function. CH__StringToName() translates 
“Jones:Sunnyvale:USA” into a three-part name so that it may be 
recognized by the Clearinghouse. The returned parameter, 
logonresult, contains one member, session, which identifies the 
session to the File Service. session may then be passed to other 
File Service calls. connected contains the courier connection 
number. A method for obtaining this connection number is 
shown in Chapter 6. Since bulk data transfer is not required in 
this example, _ BDTprocptr is set to NULL. 
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Filing6__ Open() 


The Filing6__Open function is used to make a file available for 
use. 


Open(__Connection, _ BDTprocptr, attributes, directory, 
controls, session) 


Example 


Filing6 OpenResults openresult; 
Filing6 AttributeSequence attrseq; 
Filingé Attributepathattr[1]; 


attrseq.length = 1; 
attrseq.sequence = pathattr; 
filename = "MyFile"; 


pathattr[0].type = Filing6 pathname; 
StringToAttr(filename, &pathattr[0]); 


openresult = Filing6 Open(connected, NULL, attrseq, 
Filing6 nullHandle, nullControls, session); 


In the preceding example, the file “MyFile” will be opened for 
use. Since no other parameters for the attrseq argument are 
specified, the highest version number for “MyFile” will be 
opened. Filing6__nullHandle implies that the starting directory 
to begin the search for the file is the root directory. 
nullControls indicates that no controls are specified. session is 
the session handle returned from an earlier call to 
Filing6__Logon(). The returned parameter openresult has one 
member, handle, which may be passed as an argument to all 
calls that are to access the file during the current session. 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so _BDTprocptr is set to NULL. 





Inbasket2.h 


Inbasket2__ChangeMessageStatus() 
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The Inbasket2__ChangeMessageStatus() function is used to 
update a specified range of messages from new to known. 


Inbasket2__ChangeMessageStatus(__Connection, 
__BDTprocptr, range, changeUserDefinedStatus, 
newUserDefinedStatus, session) 


Example 
Inbasket2_ Range range; 
Boolean changeUserDefinedStatus; 
LongCardinal newUserDefinedStatus; 


range.low =nullindex; 
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range.high = 10; 

changeUserDefinedStatus = 1; 

newUserDefinedStatus = Inbasket2__ known; 

(void)Inbasket2 ChangeMessageStatus(connected, 
NULL, range, changeUserDefinedStatus, 
newUserDefinedStatus, inbasketsession); 


In the preceding example, the first ten inbasket messages are 
updated to known. The range is specified by range.low and 
range.high. Setting changeUserDefinedStatus to a 1 causes the 
existenceOfMessage parameter to be set to KNOWN and 
userDefinedStatus to be updated with the value of 
newUserDefinedStatus, or “Inbasket2__known” in this example. 
inbasketsession is defined by logonresult.session from 
Inbasket2__Logon(). Bulk data transfer is not required, so 


__BDTprocptr is set to NULL. connected contains the courier 


connection number. A method for obtaining this connection 
number is show in Chapter 6. 


The Inbasket2__ Delete() function is used to remove one or 
more contiguous messages from the inbasket. 


Inbasket2__Delete(__Connection, _ BDTprocptr, range, 
session) 


Example 
Inbasket2_ Range range; 


range.low = 3; 
range.high =nulllndex; 


(void)Inbasket2__Delete(connected, NULL, range, 
inbasketsession); 


In the preceding example, the inbasket messages between the 
third and last will be deleted. The range of messages to be 
deleted is defined by the range.low and range.high arguments. 
inbasketsession is defined by logonresult.session from 
Inbasket2__Logon. connected contains the courier connection 
number. A method for obtaining this connection number is 
shown in Chapter 6. Bulk data transfer is not required, so 
__BDTprocptr is set to NULL. 


The Inbasket2__GetSize() function is used to retrieve a tally of 
the disk space occupied by all the messages in an inbasket. 


Inbasket2__GetSize(__Connection, _ BDTprocptr, 
inbasket, credentials, verifier) 


Example 
Inbasket2__GetsizeResults getsizeresult; 
Authentication2 Credentials credentials; 
Authentication2 Verifier verifier; 
char inbasketptr; 
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inbasketptr = “Jones:Sunnyvale: USA"; 
nameptr = MakeSimpleCredsAndVerifier(nameptr, 0, 
&credentials, &verifier); 


getsizeresult = Inbasket2 Getsize(connected, NULL, 
*CH_ StringToName(inbasketptr), credentials, verifier); 


In the preceding example, the disk space occupied by all the 
messages for “Jones:Sunnyvale:USA” will be placed into 
getsizeresult. CH__StringToName() converts inbasketptr into a 
three-part name. inbasketptr represents the mail recipient, 
“Jones:Sunnyvale:USA” in this example. credentials and verifier 
are the credentials and verifier returned by the 
MakeSimpleCredsAndVerifier() function. connected contains 
the courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. Bulk data transfer is 
not required, so __BDTprocptr is set to NULL. 


Inbasket2__Logoff() 


The Inbasket2__Logoff() function is used to end an inbasket 
session with the mail service. 


Inbasket2__Logoff(__Connection, _ BDTprocptr, session) 
Example 
(void)inbasket2__Logoff(connected, NULL, inbasketsession); 


In the preceding example, an inbasket session is terminated. the 
session terminated, inbasketsession, is that session defined by 
logonresult.session from Inbasket2__Logon. connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so _BDTprocptr is set to NULL. 


Inbasket2__Logon() 
The Inbasket2__Logon() function is used to initiate a new 
inbasket session with the mail service. 


Inbasket2__Logon(__Connection, _ BDTprocptr, inbasket, 
credentials, verifier) 


Example 
Inbasket2__LogonResults logonresult; 
Authenticati on2_ Credentials credentials; 
Authentication2 Verifier verifier; 
char *inbasketofrecipient; 


inbasketofrecipient = “Jones:Sunnyvale:USA"; 
nameptr = MakeSimpleCredsAndVerifier(nameptr, 0, 
&credentials, &verifier); 


logonresult = Inbasket2__Logon(connected, NULL, 
*CH StringToName(inbasketofrecipient),credentials, 
verifier); 


inbasketsession = logonresult.session; 
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In the preceding example, a new inbasket session for 
“Jones:Sunnyvale:USA” is initiated with the mail service. 
CH__StringToName() converts inbasketofrecipient into a three- 
part name needed by the mail service. credentials and verifier 
arguments are the credentials and verifier returned by the 
MakeSimpleCredsAndVerifier() function. inbasketsession 
contains the inbasket session handle to be passed to other 
Inbasket2 functions, such as Inbasket2__Logoff(). connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so ___BDTprocptr is set to NULL. 


The Inbasket2__MailCheck() function is used to determine the 
state of an inbasket. 


Inbasket2__MailCheck(__Connection, _ BDTprocptr, 
session) 


Example 
Inbasket2__ MailCheckResults mailcheckresult; 


mailcheckresult = Inbasket2__ MailCheck(connected, 
NULL, inbasketsession); 


In the preceding example, the state of an inbasket session is 
checked. The session to be checked is defined by 
inbasketsession, which is in turned defined by the earlier call to 
Inbasket2__Logon(). connected contains the courier connection 
number. A method for obtaining this connection number is 
shown in Chapter 6. No bulk data transfer is required, so 
__BDTprocptr is set to NULL. 


The Inbasket2__MailPoll() function is used to determine the 
state of an inbasket without initiating an inbasket session. 


Inbasket2__MailPoll(__Connection, _ BDTprocptr, 
inbasket, credentials, verifier) 


Example 
Authentication2 Credentials credentials; 
Authentication2 Verifier verifier; 
char *inbasketptr; 


inbasketpt = "Jones:Sunnyvale: USA"; 
nameptr = MakeSimpleCredsAndVerifier(nameptr, 0, 
&credentials, &verifier); 


mailpollresult = Inbasket2__ MailPoll(connected, NULL, 
” CH _StringToName(inbasketptr), credentials, verifier); 


In the preceding example, the state of the inbasket for 
“Jones:Sunnyvale:USA” is checked. connected contains the 
courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. No bulk data transfer 
is required, so __ BDTprocptr is set to NULL. 
CH__StringToName() translates the inbasketptr string into a 
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Inbasket2__RetrieveEnvelopes() 


three-part name needed by the mail service. credentials and 
verifier are the credentials and verifier obtained by the 
MakeSimpleCredsAndVerifier() function. 


The Inbasket2__RetrieveEnvelopes() function is used to extract 
a particular message (envelope) from the inbasket. 


Inbasket2__RetrieveEnvelopes(__Connection, 
__BDTprocptr, index, whichMsg, session) 


Example 


Inbasket2__RetrieveEnvelopesResults 
retrieveenvelopesresult; 


retrieveenvelopesresult = Inbasket2__RetrieveEnvelopes( 
connected, NULL, Inbasket2__nulllndex, Inbasket2__next, 
inbasketsession); 


message = retrieveenvelopesresult.index; 


In the preceding example, all messages in the inbasket are 
enumerated. The inbasket session is defined by inbasketsession 
which is in turn defined by an earlier call to Inbasket2__Logon(). 
connected contains the courier connection number. A method 
for obtaining this connection number is shown in Chapter 6. No 
bulk data transfer is required, so _ BDTprocptr is set to NULL. 
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MailTransport5__ AbortRetrival() 


The MailTransport5_ AbortRetrival() function is used to 
postpone the delivery of a message. 


MailTransport5__AbortRetrival (__Connection, 
__BDTprocptr, session) 


Example 


(void) MailTransportS AbortRetrival(con nected, NULL, 
retsession); 


In the preceding example, the mail service is directed to stop the 
retrieval process and to retain the remainder of the messages 
until the client is ready to accept them. retsession is the session 
handle returned from a previous call to 
MailTransport5__BeginRetrieval(). connected contains the 
courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. Since no bulk data 
transfer is required, _ BDTprocptr is set to NULL. 
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The MailTransport5__BeginRetrieval() function is used to 
initiate the retrieval of one or more messages from a delivery 
slot. 


MailTransport5__BeginRetrieval(__Connection, 
__BDTprocptr, deliverySlot, credentials, verifier) 
Example 


MailTransport5 BeginRetrievalResults 
beginretrievalresul 
t; 
Authentication2 Credentialscredentials; 
Authentication2 Verifier verifier; 
char *mailrecipientname; 


mailrecipientname = “Jones:Sunnyvale: USA" 


mailrecipientname = MakeSimpleCredsAndVerifier 
(mailrecipientname, 0, &credentials, &verifier); 


beginretrievalresult = 

MailTransport5 BeginRetrieval(connected, 
NULL, *CH StringToName(mailrecipientname), 
credentials, verifier); 


retsession = beginretrievalresult.session; 


In the preceding example, retsession contains the mailtransport 
session handle that can be passed to the various *Retrieval() 
functions. mailrecipientname identifies the mail slot to be 
accessed. In this example, “Jones:Sunnyvale:USA” is the mail slot. 
CH__StringToName() translates mailrecipientname into a three- 
part name so that it may be recognized by the Clearinghouse. 
credentials and verifier are the credentials and verifier returned 
from the call to the MakeSimpleCredsAndVerifier. connected 
contains the courier connected number. A method for obtaining 
this connection number is shown in Chapter 6. Since bulk data 
transfer is not required, _ BDTprocptr is set to NULL. 


The MailTransport5__EndPost() function is used to signal the 
mail service that the message initiated by BeginPost() is 
complete and no more data is to follow. 


MailTransport5__EndPost(__Connection, _ BDTprocptr, 
session, abortPost) 


Example 


MailTransportS EndPostResults endpostresult; 
Boolean abortPost; 


abortPost = 0; 


endpostresult = MailTransport5 EndPost(connected, NULL, 
session, abortPost); 
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In the preceding example, abortPost is set to 0, indicating that 
the message will be sent to the recipients listed in an earlier call 
to MailTransport5__BeginPost(). session is defined by the 
session handle returned from an earlier call to 
MailTransport5__BeginRetrieval(). connected contains the 
courier connection number. A method for obtaining this 
connection number is shown in chapter 6. Bulk data transfer is 
not required, so _BDTprocptr is set to NULL. 


MailTransport5__EndRetrieval() 


The MailTransport5__EndRetrieval() function is used to end the 
current delivery slot retrieval sequence. 


MailTransport5__EndRetrieval(__Connection, 
__BDTprocptr, session) 
Example | 


(void)MailTransportS EndRetrieval(connected, NULL, 
retsession); 


In the preceding example, the current delivery slot retrieval 
sequence is terminated. retsession is defined by the session 
handle returned from an earlier call to 
MailTransport5__BeginRetrieval(). connected contains the 
courier connection number. A method for obtaining this 
connection number is shown in chapter 6. Bulk data transfer is 
not required, so ___BDTprocptr is set to NULL. 


MailTransport5__MailPoll() 


The MailTransport5_ MailPoll() function is used to determine if 
messages are present in a delivery mail slot. 


MailTransport5__MailPoll (__Connection, _ BDTprocptr, 
deliverySlot, credentials, verifier) 


Example 


MailTransportS MailPollResults mailpollmtresult; 
Authentication2 Credentialscredentials; 
Authentication2 Verifierverifier; 

char *mailrecipientname; 


mailrecipientname = "“Jones:Sunnyvale: USA" 
mailrecipientname = MakeSimpleCredsAndVerifier 
(mailrecipientname, 0, &credentials, &verifier); 


mailpollmtresult = MailTransport5 MailPoll(connected, 
NULL, *CH_ StringToName(mailrecipientname), 
credentials, verifier); 


In the preceding example, the Boolean mailpollmtresult will 
indicate the presence of mail in the delivery slot or an empty 
delivery slot. A TRUE indicates there is mail ready for retrieval, a 
FALSE indicates that the delivery slot is empty. 
CH__StringToName() will translate the mail recipient’s name into 
a three-part name so that it can be recognized by the 
Clearinghouse. credentials and verifier are the credentials and 
verifier returned by the call to the 
MakeSimpleCredsAndVerifier(). connected contains the 
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courier connection number. A method for obtaining this 
connection number is shown in Chapter 6. Since bulk data 
transfer is not required, _ BDTprocptr is set to NULL. 


The MailTransport5_ RetrieveEnvelope() function is used to 
extract the header information from a delivery slot mail. 


MailTransport5__RetrieveEnvelope(__Connection, 
__BDTprocptr, session) 


Example 


MailTransportS RetrieveEnvelopeResults 
retrieveenveloperesult; 


retrieveenveloperesult = MailTransport5 RetrieveEnvelope 
(connected, NULL, retsession); 


In the preceding example, retrieveenveloperesult will contain 
two members: empty and envelope. The empty member will 
indicate whether the active delivery slot is empty or if it has 
envelopes available. envelope will be the envelope itself. 
retsession is defined by the session handle returned from an 
earlier call to MailTransport5__BeginRetrieval(). connected 
contains the courier connection number. A method for 
obtaining this connection number is shown in chapter 6. Bulk 
data transfer is not required, so __BDTprocptr is set to NULL. 
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A. Additional programs 


This appendix provides several sample programs that may be 
helpful to the programmer using the XNS portion of the 
Document Interfaces Toolkit. These programs are not supported 
items, but are given here as a helpful hint to the programmer. 
To use these programs, you must type them onto your 
workstation, and compile them. 


The first program, simpleauth.c, contains the procedure definition 
for MakeSimpleCredsAndVerifier, used in Chapter 7. The next 
four programs, attribute.c, getservice.c, gettype.c, and misc.c, 
may be used with calls to the Filing service. These contain various 
miscellaneous procedures that are identified within each 
program. Be sure to include these programs when you compile 
your XNS code. The last file, papersize.h, is a header file that 
contains paper size definitions. This header file may be used 
with programs interfacing to the Printing service. 





simpleauth.c 


/** simpleauth.c 1.3, last change 11/12/88 **/ 
static charsccsid[] = "@(#)simpleauth.c\t\t1.3"; 


#include <stdio.h> 

#include <courier/Authenti1.h> 
#include <courier/Authenti2.h> 
#include <ctype.h> 

#include <termio.h> 


extern char *CH NameToString(/* chname */); 
static voidexpand name(/* char * name, char * buf, 
int buflen */); 
static Authentication2 Clearinghouse Name * getXNSuser (/* 
char * name, char * passwd, Cardinal * hpasswdp */); 
static Cardinal hashpass (/* char * hpw */); 
static void password prompt (/* char * buf, int buflen */); 
extern char * strchr(); 
static Authentication2 Clearinghouse Name*str to chname 
(/* char * name */); _ _ — 
static voiduser prompt (/* char * buf, int buflen */); 


static void 

expand name(name, buf, buflen) 
char *name; 
char * buf; 
int buflen; 


char *domain; 
int len; 
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} 


if (strlen(name) > = buflen) 
return; 
strcpy(buf, name); 
if (domain = strchr(name, ':')) { 
if (strchr(&domain[1], ':')) 
return; 
telse { 
strcat(buf, ":"); 
len = strien(buf); 
cour get value("default domain", &bufflen], 
buflen-len); 


strcat(buf, ":"); 

len = strlen(buf); 

cour get value("“default organization", &buf[len], 
buflen-len):; 3 


static Authentication2 Clearinghouse Name * 
getXNSuser (name, passwd, hpasswdp) 


} 


char *name; 
char * passwd; 
Cardinal * hpasswdp; 


char buf([85]; 
static char name_buf[85]; 
Authentication2 Clearinghouse Name * chname; 


if (Iname) { 
cour get value("user name", buf, sizeof(buf)); 
if (!buf[0]) £ 
user prompt(buf, sizeof(buf)); 
if (!buf[0]) 
return str_ to chname(" ae ie 
} 


name = buf; 
} 
expand name(name,name_ buf,sizeof(name _buf)); 
if(name  buf[0]) _ _ 
cour set value("username",name_ buf); 
if (Ipasswd) { = 
cour get value("user password", buf, sizeof(buf)); 
if (!buf[0]) — 
password prompt(buf, sizeof(buf)); 
passwd = buf; 


} 
if (passwd[0}) 
cour set value("user password", passwd); 
*hpasswdp = hashpass(passwd); 
returnstr to chname(name__ buf); 


static Cardinal 
hashpass (hpw) 


char *hpw; 
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unsigned long hash; 
char ch; 


hash = 0; 

while ((ch = *hpw+ +)! = ‘\0') { 
hash = (hash < < 16) + (isupper(ch) ? tolower(ch) : ch); 
hash % = 65357; 


} 

return (Cardinal)hash; 
} 
char * 


MakeAuth1SimpleCredsAndVerifier (name, passwd, credentials, 


verifier) 

char *name; 

char * passwd; 

Authentication! Credentials* credentials; 
Authentication! Verifier* verifier; 


{ 
Authentication! ClearinghouseName * chname; 
Cardinal length; 
Unspecified * data, * buf, * seq; 
Cardinal c1; 
chname = (Authentication! ClearinghouseName *) 
getXNSuser(name, passwd, &c1); 
if (credentials) { 
credentials->type = 
Authentication! simpleCredentials; 
length = 7 
sizeof Authentication! ClearinghouseName 
(chname); _ 
data = Allocate(length); 
(void)externalize Authentication! ClearinghouseName 
(chname, data); | -_ 
seq = credentials- >value.sequence = Allocate(length); 
credentials->value.length = length; 
buf = data; 
for(; length > 0; length--, seq + +) 
buf + = internalize Unspecified(seq, buf); 
free(data); _ 
} 
if (verifier) { 
verifier->length = 1; 
verifier->sequence = Allocate(sizeof Unspecified(0)); 
verifier->sequence[0] = (Unspecified)c1; 
return CH NametToString(chname); 
} 
char * 


MakeSimpleCredsAndVerifier (name, passwd, credentials, 


verifier) 

char *name; 

char * passwd; 

Authentication2 Credentials* credentials; 
Authentication2__Verifier* verifier; 
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Authentication2 Clearinghouse Name * chname; 
Cardinal length; _ 

Unspecified * data, * buf, * seq; 

Cardinal c1; 


chname = getXNSuser(name, passwd, &c1); 
if (credentials) { 
credentials->type = 
Authentication2 simpleCredentials; 
length = 
sizeof Authentication2 Clearinghouse Name 
(chname); _ _ 
data = Allocate(length); 
(void)externalize Authentication2 Clearinghouse Name 
(chname,data); aa _ _ 
seq = credentials->value.sequence = Allocate(length); 
credentials->value.length = length; 
buf = data; 
for (; length > 0; length--, seq + +) 
buf + = internalize Unspecified(seq, buf); 
free(data); _ 


} 

if (verifier) { 
verifier->length = 1; 
verifier->sequence = Allocate(sizeof Unspecified(0)); 
verifier->sequence[0] = (Unspecified)c1; 


returnCH NameToString(chname); 


} 


Static void 

password prompt (buf, buflen) 
char * buf; 
int buflen; 

{ 

registerint ch; 

register char * cp; 


int Iflag; 

structtermio termio1; 

int tty fd; 

FILE *tty fp; 

buf[0] = ‘\0'; 

if ((tty fd = open("/dev/tty", 2)) = = -1) 
return; 


tty fp = fdopen(tty fd, “r"); 
setbuf(tty fp, (char *)0); 
ioctl(tty fd, TCGETA, &termio1); 
lflag = termio1.c_ Iflag; 
termiol.c_ Iflag &= “ECHO; 
ioctl(tty fd, TCSETA, &termio1); 
fprintf(stderr, “Enter XNS password: “); 
fflush(stderr); 
for (cp = buf; (ch = getc(tty fp))!= EOF; ){ 

if(ch = = ‘\n' || ch = = ‘\r') 

break; 
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if (cp < &buf[buflen]) 
*cp + + = ch; 
} 
*cp = ‘\0; 
fprintf(stderr, "\n"); 
fflush(stderr); 
termiol.c_ Iflag = Iflag; 
ioctl(tty fd, TCSETA, &termio1); 
fclose(tty _ fp); 
} 


static Authentication2 Clearinghouse Name * 
str_ to chname (name) 

char *name; 
{ 


static Authentication2 Clearinghouse Name result; 


if (name) { 
result.object = name; 
if (name = strchr(result.object, ':')) { 
*name+ + = ‘\0': 
result.domain = name; 
if (name = strchr(name,':')) { 
*name+ + = ‘\0'; 
result.organization = name; 
return &result; 
} 
} 


return (Authentication2 Clearinghouse Name *)0; 


} 


static void 

user prompt (buf, buflen) 
char * buf: 
int buflen; 


char *cp; 
FILE ™* tty; 


buf[0] = ‘\0'; 
if (tty = fopen("/dev/tty", "r+")) { 
setbuf(tty, (char *)NULL); 
fprintf(stderr, “Enter XNS username: "); 
fflush(stderr); 
fgets(buf, buflen, tty); 
if (cp = strchr(buf, ‘\n’)) 
*cp = ‘\0; 
if (tty ! = stdin) 
fclose(tty); 
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attribute.c 
/** attribute.c 1 **/ 
static char sccsid[] = "@(#)attribute.c\t\t1.1"; 


#ifdef FILING4 

#include "filingV4.h" 
#include "clearingV2.h" 
#endif 

#ifdef FILINGS 

#include "filingV5.h" 
#include “clearingV2.h" 
#endif 

#ifdef FILING6 

#include "filingV6.h" 
#include "clearingV3.h" 
#endif 

#ifdef FILINGSUBSET1 
#include "filingsuV1.h" 
#include “clearingV3.h" 
#endif 

#ifdef FPSUBSET3 
#include "fpsubsetV3.h" 
#include "clearingV2.h" 
#endif 


StringToAttr (str, attr) 
char * str; 
FILING Attribute” attr; 


Unspecified buf[{2049]; 
Unspecified * bp; 
Cardinal len; 


bp = buf + sizeof Cardinal(len); 

len = externalize String(&str, bp); 

(void)externalize Cardinal(&len, buf); 

internalize Sequence of Unspecified(&(attr- >value), buf); 


char * 
AttrToString (attr) 

FILING Attribute* attr; 
{ oe ; 


Unspecified buf[2049]; 
Unspecified * bp; 
Cardinal len; 

char * strval; 


externalize Sequence of Unspecified(&(attr->value), buf); 
bp = buf; oO | 

bp + = internalize Cardinal(&len, bp); 

bp + = internalize String(&strval, bp); 

return strval; _ 
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CLEARINGHOUSE Name * 

AttrToUser (attr) [* JHA. */ 
FILING Attribute * attr; 

f a 


Unspecified buf[2049];: 
Unspecified * bp; 

Cardinal len; 

CLEARINGHOUSE Name * user; 


externalize Sequence of Unspecified(&(attr->value), buf); 


bp = buf; 
bp + = internalize Cardinal(&len, bp); 

bp + = internalize String(&user->organization, bp); 
bp + = internalize String(&user->domain, bp); 


bp + = internalize String(&user->object, bp); 
return user; 


} 


UserToAttr (id, attr) 
CLEARINGHOUSE Name id; 
FILING Attribute* attr; 


{ 

Unspecified buf[{2049]; 

Unspecified * bp; 

Cardinal len; 

bp = buf + sizeof Cardinal(len); 

len = CLEARINGHOUSE externalize Name(&id, bp); 

(void)externalize Cardinal(&len, buf); 

internalize Sequence of Unspecified(&(attr->value), buf); 
, heal ig oes 


LongCardinalToAttr (val, attr) 
LongCardinal val; 
F ILING  Attribute* attr; 


{ 

Unspecified buf[3]; 

Unspecified * bp; 

Cardinal len; 

bp = buf + sizeof Cardinal(len); 

len = externalize LongCardinal(&val, bp); 

(void)externalize Cardinal(&len, buf); 

internalize Sequence of Unspecified(&(attr->value), buf); 
; ae 


LongCardinal 
AttrToLongCardinal (attr) 

FILING Attribute* attr; 
f _ 


Unspecified buf[2]; 
LongCardinal result; 


(void)externalize Unspecified(attr->value.sequence, buf); 


(void)externalize Unspecified((attr- >value.sequence) + 1, 
buf + 1); 
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} 


(void)internalize LongCardinal(&result, buf); 
return result; 


BooleanToAttr (val, attr) 


{ 


} 


int 


int val; 
FILING Attribute* attr; 


Boolean boolval; 
Unspecified buf[3]; 
Unspecified * bp; 
Cardinal len; 


boolval = (Boolean) val; 

bp = buf + sizeof Cardinal(len); 

len = externalize Boolean(&boolval, bp); 

(void)externalize Cardinal(&len, buf); 

internalize Sequence of Unspecified(&(attr- >value), buf); 


AttrToBoolean (attr) 


{ 


} 


FILING Attribute* attr; 


Unspecified buf[1]; 
Boolean result; 


(void)externalize Unspecified(attr- >value.sequence, buf); 
(void)internalize Boolean(&result, buf); 
return result; 


CardinalToAttr (val, attr) 


Cardinal val; 
FILING Attribute* attr; 


{ 

Unspecified buf[3]; 

Unspecified * bp; 

Cardinal len; 

bp = buf + sizeof Cardinal(len); 

len = externalize Cardinal(&val, bp); 

(void)externalize Cardinal(&len, but); 

internalize Sequence of Unspecified(&(attr->value), buf); 
} 
Cardinal 


AttrToCardinal (attr) 


{ 


FILING Attribute* attr; 


Unspecified buf[2]; 
Cardinal result; 


(void)externalize Unspecified(attr->value.sequence, buf); 


(void)internalize Cardinal(&result, buf); 
return result; 
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FilelIDToAttr (value, attr) 
Cardinal valuef]; 
FILING Attribute* attr; 


{ 

Unspecified buf[6]; 

Unspecified *bp; 

Cardinal len; 

bp = buf + sizeof Cardinal(len); 

len = FILING externalize FilelD(value, bp); 

(void)externalize Cardinal(&len, buf); 

internalize Sequence of Unspecified(&(attr- > value), buf); 
; = i 


Unspecified * 
AttrToFilelD (attr) 
FILING Attribute” attr; 


{ 
Unspecified * bp; 
Unspecified buf[6]; 
bp = Allocate(FILING sizeof FilelD(0)); 
(void)FILING externalize FilelD(attr->value.sequence, buf); 
(void)FILING internalize FilelD(bp, buf); 
returnbp; a 
} 





getservice.c 
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/** getservice.c 1.1 **/ 
static char sccsid[] = “@(#)getservice.c\t\t1.1"; 


extern char * strchr(); 
extern char * strrchr(); 


getserviceandfile (name, srvcptr, fileptr) 
char *name; 
char **srvcptr; 
char ** fileptr; 


char * sptr; 
char * fptr; 


*srvcptr = (char *)0; 

J* 

* look for Xerox forms first: 

* [host]filename 

*/ 

if (sptr = strchr(name, ‘[')) £ 

if (fptr = strrchr(sptr, ‘]')) £ 

*fotr = ‘\0'; 
*srvcptr = sptr + 1; 
*fileotr = fptr + 1; 
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return 1; 


} 


return 0; 
} 
| ia 
* (host)filename 
*/ 
if (sptr = strchr(name, ‘(')) { 
if (fptr = strchr(sptr, ‘)')) { 
*fotr = ‘\0'; 
*srvcptr = sptr + 1; 
*fileptr = fptr + 1; 
return 1; 


} 


return 0; 
} 
/* 
* look for XNS style with trailing : delimiter 
* (assumes no: in file name, use alternate spec instead) 
* object:domain:organization: filename 
* domain & organization are optional 


*/ 

if (fptr = strrchr(name, ':')) { 
*fotr = ‘\0'; 
*srvcptr = name; 
*fileotr = fptr + 1; 
return 1; 

} 

return 1; 


/** gettype.c 1.1 **/ 


static char sccsid[] = "@(#)gettype.c\t\t1.1"; 


#include <stdio.h> 

#include <sys/types.h> 
#include <sys/stat.h> 
#include <courier/filetypes.h> 
#include <courier/courier.h> 


#define CHARS TO READ2048 


/* 


* routine: 


* 


get type 


* input: 


* 
* 


* 


pointer to pathname of file 

read first CHARS TO READ 

if it contains "RasterEncoding/", assume RES (return 
TYPE VPCanvas) 

if it contains "Interpress/Xerox/", assume IP (return 
TYPE __Interpress) 
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* if acharis 0 or high order bit set, assume binary (return 
tUNSPECIFIED) 
* else assume text (tText) 
(Note order of RES/IP checking is important since RES files 
contain 
IP string also) 


+ 


returns: 
LongCardinal containing filing defined file type 


+ £¢ + + 


*/ 

extern LongCardinal GetTypeAttribute(Q; 
static Boolean is typeQ; 

extern char *strrchr(); 


typedef struct st_s { 


char * st_string; 
LongCardinal st_type; 
}ST, * STP; 


static STdoc_types[] = { 
{"text",  TYPE_A}, 


{ "binary", TYPE_I}, 

{ “directory”, TYPE_Directory }, 

{ “vp doc", TYPE_VP }, 

{ "interpress", TYPE_Interpress }, 
{"vp canvas", | TYPE_VPCanvas}, 

{ “vp dictionary", TYPE_VPDictionary }, 
{"“vp mailnote", TYPE_VPMailNote }, 

{ “vp reference", TYPE_VPReference }, 

{ "serialized", | TYPE_S}, 

{ “vp filedrawer", TYPE_VPDrawer }, 

{ “vp application", | TYPE_VPApplication }, 
{"“vp spreadsheet", TYPE_VPSpreadsheet }, 
{ “vp book", TYPE_VPBook }, 

{ “vp recordfile", TYPE_VPRecordsfile }, 

{ "vp calendar", TYPE_VPCalendar }, 

{ “vp icons", TYPE_VPlcons }, 

{ “printerfont", TYPE_Font}, 

{"860 doc", TYPE_860}, 

{0} 


LongCardinal 

get_type (pathname) 
char * pathname; 

{ 


int fd; 

char buffer[CHARS_TO_READ]; 
int count; 

char * ptr; 

LongCardinal type; 

struct stat fs; 


if (stat(pathname, &fs) = = -1) 
return(TYPE_|); /* if error, assume tUnspecified */ 
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/* 
* if not a regular file look for directory... 
* if a directory and in root, then assume file drawer 
*/ 
if ((fs.st mode&S IFMT)!=S_ IFREG){ 
if (fsst mode&S IFDIR){ — 
if (strrchr(pathname, '/') = = pathname) 
return TYPE VPDrawer; 
else _ 
return TYPE Directory; 
}else a 
return TYPE |; 


} 
if ((fd = open(pathname, 0)) < 0) 
return TYPE |; /* if error, assume tUnspecified */ 
if (count = read(fd, buffer, sizeof(buffer))) { 
if(is type(RESHDR, buffer, count) = = TRUE) 
type = TYPE VPCanvas; 
else if(is type(INTERPRESSHDR, buffer, count) = = 
TRUE) — 
type = TYPE Interpress; 
else if(is type(VPHDR, buffer, count) = = TRUE) 
type = GetTypeAttribute(fd); 
else { 
type = TYPE A; /* assume tAsciiText */ 
for (ptr = buffer; ptr < &buffer[count - 1]; ptr+ +) { 
/* if 0 or high order bit */ 
if (*ptr = = 0 || (*ptr & 0200)) £ 
/* assume tUnspecified */ 


type= TYPE I; 
break; _ 
} 
} 
} 
} else 
type = TYPE |; /* if error, assume tUnspecified */ 
close(fd); 7 
return type; 


} 


static Boolean 
is type(type string, file snip, file snip len) 
~ char *type string; — nn 
char *file snip; 
int file snip len; 


char string[128]; | /* 128 should be enough for all cases 
* 
/ 

char *cp, * boundary; 

int type string len; 


type string len = strlen(type string); 
if (file snip len > sizeof(string)) 
file snip len = sizeof(string); 
if (file snip len<type string len) 
return FALSE; _ - 
memcpy(string, file sni p, file _snip_len); 
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lowercasen(string, file snip len); 

boundary = &string[file snip len-type string len]; 

for (cp = string; cp < boundary; cp + +) ime 
if(memcmp(cp, type string, type string len) = = 0) 


return TRUE; 
} 
return FALSE: 
} 
char * 


typetostring (type) 
LongCardinal type; 


register STP st; 
static char string[80]; 


for (st = &doc_types[0]; st->st__ string; st + +){ 
if (type = = st->st__ type) 
return st- >st_ stri NG; 


} 
sprintf(string, "%ld", (long)type); 
return string; 


} 


LongCardinal 
stringtotype (string) 

char * string; 
{ 


extern long atol(/* char * str */); 
register STP st; 


if (!*string) 
return(TYPE VPMailNote); 
lowercase(string); 
for (st = &doc types[0]; st->st string; st+ +) { 
if (stremp(string, st->st string) = = 0) 
return st->st_ type; — 


return (LongCardinal)atol(string); 





MISC.C 
/** misc.c 1.1 **/ 
static char sccsid{] = “@(#)misc.c\t\t1.1"; 
#include <ctype.h> 
/* change case to upper*/ 
char * 
uppercase (string1) 


char ™*string1; 


registerchar *string2 = string1; 
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while (*string2) { 
if (islower(*string2)) 
*string2 = *string2 - 040; 
string2 + +; 
} 


return string]; 


} 


/* change counted string to upper */ 
char * 
uppercasen (string1, count) 

char * string]; 

int count; 


{ 


registerchar *string2 = string1; 


while (count--) { 
if (islower(*string2)) 
*string2 = *string2 - 040; 
string2 + +; 
} 


return string1; 


} 


/* change case to lower */ 
char * 
lowercase (string 1) 

char * string]; 


{ 


registerchar *string2 = string1; 


while (*string2) { 
if (isupper(*string2)) 
*string2 = *string2 + 040; 
string2 + +; 
} 


return string1; 


} 


/* change counted string to lower */ 
char * 
lowercasen(string1, count) 

char *string1; 

int count; 


{ 


registerchar *string2 = string]; 


while (count--) { 
if (isupper(*string2)) 
*string2 = *string2 + 040; 
string2 + +; 
} 


return string1; 


} 
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papersize.h 
/** papersize.h 1.2 **/ 
/* $Header: papersize.h,v 1.1 87/07/01 11:25:11 ed Exp $ */ 


/* 
*$Log: papersize.h,v$ 
* 


*/ 


static struct { 
char * sizename; 
int sizevalue; 

} papersizetable[] = { 
“usLetter', (int) usLetter, /* 1 */ 
“usLegal”, (int) usLegal, /* 2 */ 
"a0", (int) a, /* 3 */ 

"al", (int) a1, /* 4 */ 

"a2", (int) a2, /* 5 */ 

"a3", (int) a3, /* 6 */ 

"a4" (int) a4, /* 7 */ 

"a5", (int) a5, /* 8 */ 

"a6", (int) a6, /* 9 */ 

"a7", (int) a7, /* 10 */ 
"a8", (int) a8, /* 11 */ 
"a9", (int) a9, /* 12 */ 
"iS0B0", (int) isoBO, /* 13 */ 
"i$0B1", (int) isoB1, /* 14 */ 
"isoB2", (int) isoB2, /* 15 */ 
“is0B3", (int) isoB3, /* 16 */ 
"1is0B4", (int) isoB4, /* 17 */ 
“is0B5", (int) isoB5, /* 18 */ 
"is0B6", (int) isoB6, /* 19 */ 
“is0B7", (int) isoB7, /* 20 */ 
"is0B8", (int) isoB8, /* 21 */ 
"is0B9", (int) isoB9, /* 22 */ 
"is0B 10", (int) isoB10, /* 23 */ 
"yisBO", (int) jisBO, /* 24 */ 
“jisB1", (int) jisB1, /* 25 */ 
"jisB2", (int) jisB2, /* 26 */ 
"jisB3", (int) jisB3, /* 27 */ 
"jisB4", (int) jisB4, /* 28 */ 
"jisB5", (int) jisB5, /* 29 */ 
"jisB6", (int) jisB6, /* 30 */ 
"jisB7", (int) jisB7, /* 31 */ 
"jiSB8", (int) jisB8, /* 32 */ 
"jiSB9", (int) jisB9, /* 33 */ 
"jisB10", (int) jisB10, /* 34 */ 
“a10", (int) a10, /* 35 */ 
(char *) 0,0 
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A 
Authenti2.h, 6-8, 6-9, 7-1 
Authenti2__ChangeSimpleKey(), 6-11 
Authenti2__ChangeStrongKey(), 6-11 
Authenti2__CreateStrongKey(), 6-12 
Authenti2__CheckSimpleCredentials(), 6-12, 7-1 
Authenti2__DeleteSimpleKey(), 6-12 
Authenti2_ _DeleteStrongKey(), 6-12 
Authenti2__GetStrongCredentials(), 6-13, 7-2 
Authentication service, 1-2, 6-8 

function(s), see specific function(s) name 


B 

__BDTprocptr, 6-1, 6-2, 6-3, 7-2, 7-3, 7-4, 7-5, 
76,77 7-8 729: P10, TAG TANG, 1 
F19..7-20- 7-91, 7-22. 7-03, 7-04.75 

BulkData1l__immediateSink, 6-3, 6-4, 7-11, 7-12, 

7-13, 7-16 

BulkData1__immediateSource, 6-3 


C 
connected, 7-2, 7-3, 7-4, 7-5, 7-6, 7-7, 7-8, 7-9, 
7-10, 7211, 7212; 7-13, 7214, 7=15,-7-16; 7-17, 
7-18, 7-19, 7-20, 7-21, 7-22, 7-23, 7-24, 7-25 
__Connection, 6-1, 6-2, 6-3 
CHEntrie0.h, 6-9, 7-3, 7-5, 7-7, 7-8, 7-9, 7-16 
CH__StringToName, 7-2, 7-3, 7-4, 7-5, 7-6, 7-7, 
7-67-9710, 7-914 7 AS NT, 7-007 
23, 7-24 
Clearing2__AddGroupProperty(), 6-11 
Clearing2__AdditemProperty(), 6-11, 7-3 
Clearing2__AddMember(), 6-11, 7-4 
Clearing2__AddSelf(), 6-11, 7-4 
Clearing2__Changeltem(), 6-11, 7-5 
Clearing2__CreateAlias(), 6-12, 7-6 
Clearing2__CreateObject(), 6-12, 7-6 
Clearing2__DeleteAlias(), 6-12, 7-7 
Clearing2__DeleteMember(), 6-12, 7-7 
Clearing2__DeleteObject(), 6-12, 7-8 
Clearing2__DeleteProperty(), 6-12, 7-8 
Clearing2__DeleteSelf(), 6-12, 7-9 
Clearing2__IsMember(), 6-13, 7-9, 7-10 
Clearing2__List(), 6-3 
Clearing2__ListAliases(), 6-3, 6-13 
Clearing2__ListAliasesOf(), 6-3, 6-13, 7-10 
Clearing2__ListDomain(), 6-3, 6-13, 7-11 
Clearing2__ListDomainServed(), 6-3, 6-13, 7-12 
Clearing2__ListObjects(), 6-13, 7-12 
Clearing2__ListOrganizations(), 6-13, 7-13 
Clearing2__ListProperties(), 6-13, 7-14 
Clearing2__LookupObject(), 6-13, 7-14 
Clearing2__RetrieveAddresses(), 6-14, 7-15 
Clearing2__Retrieveltem(), 6-14, 7-15 
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Clearing2__RetrieveMembers(), 6-3, 6-14, 7-16 
Clearing2.h, 6-8 
Clearinghouse service, 1-2, 6-8 
function(s), see specific name 
create 
document(s), see document(s) 
graphic(s), see graphic(s) 
table(s), see table(s) 


D 
desktop 
function(s), see specific function(s) name 
Desktop.h, 4-1 
Doc!C.h, 4-1, 4-3 
Doc!CProps.h, 4-1 
document(s) 
copying, 2-4, 4-43 


creating, 1-1, 2-3, 2-3, 4-2, 4-3, 4-5, 4-7, 4-8, 
4-17, 4-18, 4-26, 4-42, 5-1, 5-3, 5-5, 5-6, 
5-7 


enumerating, 1-1, 4-9, 4-10, 4-11, 4-14, 4-22, 
4-25, 4-34, 4-37, 4-42, 5-3, 5-4 
function(s), see specific function(s) name 
moving, 2-4, 2-5, 3-4, 4-3, 4-6, 4-9, 4-17, 4-27, 
4-44, 5-7 

di__abort(), 4-41, 5-1 

di__apaframe(), 4-2, 4-3, 4-17, 4-18, 4-25, 4-31, 
4-41, 5-1, 5-6 

di__apbreak(), 4-6, 4-41 

di__apchar(), 4-41 

di__apfield(), 4-42, 5-2 

di__apfntile(), 4-42 

di__apfstyle(), 4-42 

di__apindex(), 4-42 

di__apnewpara(), 4-6, 4-42 

di__appfc(), 4-42 

di_appstyle(), 4-42 

di_aptext(), 4-5, 4-42, 5-2, 5-3 

di__aptofillin(), 4-42, 5-3 

di__aptotxtInk(), 4-42 

di__clearfillinQ), 4-42 

di__cleartxtInk(), 4-42 

di__close(), 4-9, 4-9, 4-14, 4-22, 4-33, 4-34, 4-42, 
5-3 

di_enumerate(), 4-9, 4-10, 4-11, 4-14, 4-22, 
4-25, 4-34, 4-37, 4-42, 5-3, 5-4 

di_enumfilling, 4-42 

di_enumprocs, 4-9, 4-10, 4-13, 4-21, 4-37 

di_enumstyle(), 4-42, 5-4, 5-5 

di_enumtxtink(), 4-42 

di_finish(), 2-3, 2-5, 4-3, 4-6, 4-17, 4-18, 4-27, 
4-42 

di_getenumprocsdef, 4-10, 4-11, 4-13, 4-22, 
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4-33, 4-37, 4-38, 5-4 
di__ getfieldfromname(), 4-42 
di_getfnprops(), 4-42 
di_getmode(), 4-42, 5-5 
di_open(), 2-3, 4-8, 4-9, 4-13, 4-21, 4-42, 5-5 
di_relcap(), 4-42 
di_relfield(), 4-42 
di_ relfoot(), 4-42 
di_relhead(), 4-42 
di_relindex(), 4-42 
di_relnum(), 4-42 
di__reltxt(), 4-42 
di_setfnprops(), 4-42 
di_setmode(), 4-6, 4-42, 5-5 
di__setpara(), 4-6, 4-42 
di__start(), 2-3, 4-2, 4-3, 4-5, 4-7, 4-8, 4-17, 
4-18, 4-26, 4-42, 5-1, 5-3, 5-5, 5-6, 5-7 
di_startap(), 4-3, 4-25, 4-42, 5-3, 5-5 
di_starttext(), 4-3, 4-42, 5-6 
di__textforaframe(), 4-43 
dp__colfromname(), 4-43, 5-6 
dp__enumfrun(), 4-43 
dp__fontdesc, 4-7 
dp_fontprops, 4-7 
dp__getbaspropsdef(), 4-43 
dp__getbreakdef(), 4-4, 4-43 
dp__getcolwidthdef(), 4-43 
dp__getfielddef(), 4-43 
dp__getfnnumdef(), 4-43 
dp__getfontdef(), 4-4, 4-6, 4-7, 4-43, 5-3, 5-6, 
5-8 
dp__getfontdescdef(), 4-8 
dp__getfontelmarralltrue(), 4-43 
dp__getfontstyledef(), 4-43 
dp__getframedef(), 4-18, 4-28 
dp_getmodedef(), 4-4 
dp__getframedef(), 4-43 
dp__getindex(), 4-43 
dp__getmodedef(), 4-43 
dp__getpagedef(), 4-43 
dp__getrundef(), 4-43 
dp__getparelmarralltrue(), 4-43 
dp__getpagedef(), 4-4, 4-43 
dp__getpagedel(), 4-43 
dp__getrundef(), 4-43 
dp__gettabstopdef(), 4-43 
dp__getparelmarralltrue(), 4-43 
dp__getparadef(), 4-4, 4-43, 5-8 
dp__getparastyledef(), 4-43 
dp__gettframedef(), 4-43, 5-6 
dp__gettoc(), 4-43 
dp__namefromcol(), 4-43 
dp__wkcolfromcol(), 4-43 
dsktp__checkuser(), 4-43 
dsktp__copydoc(), 2-4, 4-43 
dsktp__deletedoc(), 2-4, 4-43 
dsktp__deletefolder(), 2-1, 4-43 
dsktp__enumerate(), 2-2, 4-43 
dsktp__getaccess(), 4-43 
dsktp__getdocref(), 2-3, 4-8, 4-9, 4-13, 4-21, 
4-33, 4-43 
dsktp__getdocpropsref(), 4-43 
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dsktp__makefolder(), 2-1, 4-44 
dsktp__movedoc(), 2-4, 2-5, 3-4, 4-3, 4-6, 4-9, 
4-17, 4-27, 4-44, 5-7 


E 

enumerate 
document(s), see document(s) 
graphic(s), see graphic(s) 
table(s), see table(s) 


F 
Filing6__ChangeAttributes(), 6-11 
Filing6__ChangeControls(), 6-11 
Filing6__Close(), 6-11 
Filing6__Continue(), 6-11 
Filing6__Copy(), 6-11 
Filing6__Create(), 6-11 
Filing6__Delete(), 6-12 
Filing6__Deserialize(), 6-3, 6-12 
Filing6__Find(), 6-12 
Filing6__GetAttributes(), 6-12 
Filing6__GetControls(), 6-12 
Filing6__List(), 6-13 
Filing6__Logon(), 6-13, 7-17 
Filing6__Logoff(), 6-13 
Filing6__Move(), 6-13 
Filing6_ Open(), 6-13, 7-18 
Filing6__Replace(), 6-13 
Filing6__ReplaceBytes(), 6-13 
Filing6__Retrieve(), 6-13 
Filing6__RetrieveBytes(), 6-14 
Filing6__Serialize(), 6-3, 6-14 
Filing6__Store(), 6-3, 6-14 
Filing6__UnifyAccessLists(), 6-14 
Filing6.h, 6-10 
Filing service, 1-2, 6-9 
FilingSu1.h, 6-8, 6-9 
folders 

creating, 2-1, 4-44 

deleting, 2-1, 4-43 

enumerating, 2-2 
function(s), see specific function(s) name 


G 
Gap3.h, 6-8 
gapcontrol.h, 6-8 
Gateway service, 1-2, 6-8 
function(s), see specific function(s) name 
getsigno(), 4-1, 4-2, 4-44, 5-7 
gi_adbacht(), 4-44 
gi_adbm(), 4-44 
gi__adcurve(), 4-18, 4-44 
gi_adellipse(), 4-44 
gi__adffield(), 4-44 
gi_adline(), 4-44 
gi_adIncht(), 4-44 
gi__adpicht(), 4-44 
gi_adpislce(), 4-44 
gi_adpoint(), 4-44 
gi__adrectangle(), 4-44 
gi_adtable(), 4-25, 4-44 
gi_adtframe(), 4-44 
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gi__adrectangle(), 4-44 
gi__apchartobtnprog(), 4-44 
gi__apnparatobtnprog(), 4-44, 5-7, 5-8 
gi__aptexttobtnprog(), 4-44 
gi__btnforaframe(), 4-44 
gi_enumbtnprog(), 4-44 
gi_enumerate(), 4-19, 4-20, 4-44 
gi__finishbtn(), 4-44 
gi__finishcht(), 4-44 
gi__finishcluster(), 4-44 
gi__finishgframe(), 4-44 
gi_finishgr(), 4-17, 4-18, 4-44 
gi_finishnbtn(), 4-44 
gi__getbachtpropsdef(), 4-44 
gi_getbmdispdef(), 4-44 
gi_getbmpropsdef(), 4-44 
gi__getbmscalpropsdef(), 4-44 
gi__getboxdef(), 4-18, 4-45 
gi_getchtappdef(), 4-45 
gi__getchtdatdef(), 4-45 
gi__getcurvepropsdef(), 4-18, 4-45 
gi__getellipsepropsdef(), 4-45 
gi__getenumprocsdef(), 4-20 
gi__getframepropsdef(), 4-45 
gi__getgframeprops(), 4-45 
gi__getgridpropsdef(), 4-45 
gi__getlinepropsdef(), 4-45 

gi__ getInchtappdef(), 4-45 

gi_ getinchtpropsdef(), 4-45 
gi__getpislcepropsdef(), 4-45 
gi__getpointpropsdef(), 4-45 

gi_ getrectanglepropsdef(), 4-45 
gi__gettframepropsdef(), 4-45 
gi_ gettrianglepropsdef(), 4-45 
gi_relbtnprog(), 4-45 
gi_setgframeprops(), 4-45 
gi__startbtn(), 4-45, 5-8 
gi__startcluster(), 4-16,4-45 
gi__startgframe(), 4-16, 4-45 
gi_startgr(), 4-16, 4-17, 4-18, 4-45 
gi_startnbtn(), 4-16, 4-45 
graphic(s) 


creating, 1-1, 4-16, 4-17, 4-18, 4-45, 5-8 


enumerating, 1-1, 4-19, 4-20, 4-44 
GraphicsIC.h, 4-1, 4-3, 4-16 


Inbasket2__ChangeBodyPartsStatus(), 6-3, 6-11 
Inbasket2__ChangeMessageStatus(), 6-11, 7-18 


Inbasket2__Delete(), 6-12 
Inbasket2__GetSize(), 6-13, 7-19, 7-20 


Inbasket2__Logon(), 6-13, 7-19, 7-20, 7-22 


Inbasket2__Logoff(), 6-13, 7-20 
Inbasket2__MailCheck(), 6-13, 7-21 
Inbasket2__MailPoll(), 6-13, 7-21 
Inbasket2__RetrieveBodyParts(), 6-14 


Inbasket2__RetrieveEnvelopes(), 6-14, 7-22 


Inbasket2.h, 6-9 
L 

libdoctk.a, 4-1 

libxnstk.a, 6-7 

libcourier.a, 6-7 
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M 
Mailing service, 1-2, 6-9 
function(s), see specific function(s) name 
MailTran5.h, 6-9 
MailTran5__AbortRetrival(), 6-11, 7-22 
MailTran5_ BeginPost(), 6-11, 7-24 
MailTran5__BeginRetrieval(), 6-11, 7-22, 7-23, 
7-24 7-25 
MailTran5__Create(), 6-12 
MailTran5__EndPost(), 6-12, 7-23 
MailTran5__EndRetrieval(), 6-12, 7-24 
MailTran5__MailPoll(), 6-13 
MailTran5__PostOneBodyPart(), 6-13 
MailTran5__RetrieveContent(), 6-14 
MailTran5_ RetrieveEnvelope(), 6-14, 7-25 
MailTran5__ServerPoll(), 6-14 
MakeSimpleCredsAndVerifier, 7-1, 7-2, 7-17, 
F220. FD, 7-227 TA 


P 
Printing3__GetPrinterProperties(), 6-12 
Printing3__GetPrintRequestStatus(), 6-12 
Printing3__GetPrinterStatus(), 6-1, 6-2, 6-12 
Printing3__Print(), 6-3, 6-13 
Printing3.h, 6-10 
Printing service, 1-2, 6-10 

function(s), see specific function(s) name 


S 
Signals.h, 4-1 


T 
table(s) 
creating, 1-1, 4-25, 4-30, 4-46, 5-8, 5-10 
enumerating, 1-1, 4-31, 4-35, 4-45 
function(s), see specific function(s) name 
TableIC.h, 4-1, 4-3, 4-24 
ti_appendrow(), 4-25, 4-30, 4-45, 5-8 
ti__deffont(), 4-45 
ti_defpara(), 4-45 
ti_ enumtable(), 4-31, 4-35, 4-45 
ti_finishtable(), 4-25, 4-31, 4-45 
ti_ getcolinfrecdef(), 4-29, 4-45, 5-8 
ti_gethdentrydef(), 4-45 
ti_getlinedef(), 4-45 
ti_ getrowentdef(), 4-30, 4-45, 5-8, 5-9 
ti__getsortkeydef(), 4-45 
ti_gettableprops(), 4-45 
ti_gettablepropsdef(), 4-29, 4-45, 5-9, 5-10 
ti_maxelm(), 4-46 
ti_ startextable(), 4-25, 4-46, 5-8 
ti__starttable(), 4-25, 4-30, 4-46, 5-8, 5-10 


X-Y-Z 
XCC8, 3-2, 3-3 
Xerox Character Code Standard, 3-1, 3-2, 
XNS error handling, 6-5 
XNS service(s) 
Authentication, 1-2 
Clearinghouse, 1-2 
Printing, 1-2 
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Filing, 1-2 

Mailing, 1-2 

Gateway, 1-2 
xnstime.h, 6-9, 6-10 
XString 

comparison, 3-8, 3-9 

concatenating, 3-7 

conversion, 3-3 

format, 3-1 

function(s), see specific function(s) name 

structure, 3-2 
XCharcode(), 3-3, 3-5, 4-46 
XCharmake(), 3-3, 4-46 
XCharset(), 3-3, 3-5, 4-46 
XStrcasecmp(), 3-6, 3-9, 4-46 
XStrcaselexcmp(), 3-7, 3-10, 4-46 
XStrcat(), 3-1, 3-6, 3-7, 4-46 
XStrchr(), 3-7 
XStrcmp(), 3-6, 3-9, 4-46 
XStrcpy(), 3-6, 3-8, 4-46 
XStrdup(), 3-6, 4-46 


XStrfromASC(), 2-3, 2-5, 3-3, 3-4, 3-7, 4-4, 4-5, 
4-19, 4-21, 4-33, 4-46, 5-2, 5-3, 5-7, 5-11 
XStrfromXCC&(), 3-3, 3-4, 4-46 


XString.h, 4-1 

XStrlen(), 3-6, 4-12, 4-39, 4-46 
XStrlexcmp(), 3-6, 3-10, 4-46 
XStrlexncmp(), 3-6 
XStrncasecmp(), 3-6, 3-9, 4-46 
XStrncaselexcmp(), 4-46 
XStrncmp(), 3-6, 3-9 

XStrncat(), 3-6, 3-8, 4-46, 5-10 
XStrncpy(), 3-2, 3-6, 4-46 
XStrnlexcmp(), 3-10, 4-46 
XStrpbrk(), 3-7, 4-46 

XStrrchr(), 3-7, 4-46 

XStrsch(), 3-7, 4-46 

XStrsep(), 3-7, 4-46 

XStrtoASC(), 2-2, 3-3, 3-4, 4-12, 4-47 
XStrtoxCC8(), 3-3, 3-4, 3-5, 4-47 
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Customer Comments 


XEROX. 


VP Series Reference Library 
Document Interfaces Toolkit User Guide 


Our goal is to improve the organization, ease of use, and accuracy of this library. Your comments 
and suggestions will help us tailor our manuals to better suit your needs. 


Name: Company: 
Address: City: 


State: Zip: 





Please rate the following: 


Excellent Good Fair Poor 
1. Is the organization suitable for your needs? oO Oo O O 
2. Are you able to easily find the information you need? oO o Oo Oo 
3. Are the illustrations useful? O O O 3 
4. Overall, how would you rate the documentation? O O O O 


Did you find any errors? 
Page number / Error 


How can we improve the documentation? 


| We appreciate your comments regarding our documentation. Thank you for taking the time to reply. 
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